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PREFACE 


This manual is designed as a reference for Wang VS BASIC Version 4.0. 
The manual is divided into tv/o parts. Part I contains general 
discussions of the form of programs and data, and of the use of the 
different types of VS BASIC statements. Chapters 7 and 8 discuss 
file, printer, and workstation input and output in the VS 
environment. These discussions generally assume minimal programming 
knowledge. 

Part II contains the specific syntax for each VS BASIC instruction. 
Examples are provided along with details of the required formats. 

The discussions of the following topics in the indicated manuals may 
be helpful to users of this reference manual. 


Topic 

Manual 

Part Number 

Command Processor 
functions 

VS Programmer's Introduction 

800-1101 

Editor, Linker, and 
Symbolic Debugger 

VS Program Development Tools 

800-1307 

Procedures and 
return codes 

VS Procedure Language 

Reference 

800-1205 

Data type formats 

VS Principles of Operation 

800-1100 

DMS and file 
structure 

VS Operating System Services 
Reference 

800-1107 

WP files 

VS Programmer's Guide to VS/IIS 

800-1304 

System Utilities 

VS System Utilities Reference 

800-1303 

File Management 
Utilities 

VS File Management Utilities 
Reference 

800-1308 



Topic 

Manual 

Part Number 

COBOL 

VS COBOL 74 Reference 

800-1201 

PL/1 

VS PL/I Language Reference 

800-1209 

FORTRAN 

VS FORTRAN Language Reference 

800-1208 

RPG II 

VS RPG II Language Reference 

800-1203 

Assembly language 

VS Assembly Language Reference 

800-1200 










Part I 

Introduction to VS BASIC 






CHAPTER 1 

INTRODUCTORY CONCEPTS 


1.1 AN OVERVIEW: BASIC ON THE WANG VS 

Wang VS BASIC is a compiled, general-purpose, high-level programming 
language developed by Wang Laboratories, Inc., for use on the VS 
Operating System. This modified version of the original Dartmouth 
BASIC offers all of the original language's important features, as 
well as added capabilities that suit it for both technical and 
commercial applications. Although VS BASIC is extremely powerful and 
versatile, it is easy for beginning programmers to learn because 

• VS BASIC statements closely resemble the English language. This 
provides beginning programmers with clues to the VS BASIC meaning. 

In situations where formulas must be used, the VS BASIC language 
resembles standard algebraic notation and other programming 
languages such as FORTRAN. 

• You do not need to know much about VS BASIC to write a simple 
program, and do not need to learn about the advanced capabilities of 
BASIC until a specific need for those capabilities arises. 

VS BASIC incorporates diverse features that aid in program development 
and increase data processing versatility, including 

• Variable names up to 64 characters long — Long variable names 
enable you to assign mnemonic and self-explanatory names. Programs 
using such variable names are easier to read and debug than are the 
limited two-character names found in most BASIC implementations. 

• Alphanumeric statement labels — Any statement in a VS BASIC program 
can be identified by an arbitrary statement label up to 64 
characters long, which can be referenced in any program branch 
statement (GOTO, IF...THEN...ELSE, etc.). This allows you to write 
programs without line numbers, as is necessary in most BASIC 
implementations. You can give blocks of program code mnemonic 
labels that indicate their function, again increasing program 
readability and ease of debugging. 
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• Workstation, file^ and printer I/O statements — The ACCEPT and 
DISPLAY statements enable BASIC programs to make full use of the 
capabilities of the VS workstation, allowing sophisticated screen 
formatting and use of Program Function (PF) keys for data entry and 
program control. The FMT and Image {%) statements allow precise 
control over format of file and printer I/O. 

• Integer and floating-point formats — Numeric data can be stored and 
manipulated in either format. Using integer format can increase 
both the speed and efficiency of memory use. 

• Float decimal support — VS BASIC programs running on all VS systems 
except the VS50 and VS80 can perform floating-point operations in 
the float decimal rather than the float binary representation. 

Float decimal operations avoid the inaccuracies introduced into 
calculations when float binary values are converted to hexadecimal 
equivalents. When the Minimal ANSI compiler option is selected 
(MINANS=yES, refer to Appendix B), only float decimal is supported. 

• Alphanumeric operations — Extensive facilities are provided for 
manipulating alphanumeric data. Substrings can be extracted from 
strings of characters, and strings can be concatenated (put 
together) or searched for particular substrings. 

• Boolean logic functions on binary values — All 16 Boolean functions 
of two variables are available in VS BASIC. Results can be used in 
alphanumeric expressions or output as hexadecimal numbers or ASCII 
character strings. 

• Intrinsic and user-defined functions — VS BASIC provides a full set 
of arithmetic and trigonometric functions. In addition, you can 
define and name any arbitrary numeric function to be used in a 
program. 

• Multilingual subroutines — Programs written in VS BASIC can call 
subroutines written in other languages (e.g., COBOL, PL/I, and 
Assembly language) and vice versa. 


1.2 COMMUNICATING WITH THE VS 


1.2.1 The Workstation 


The principal means of user communication with the VS is through the 
VS workstation. The workstation is a terminal consisting of a Cathode 
Ray Tube (CRT) display screen and a typewriter-like keyboard. The 
screen displays output from the computer and text you type on the 
keyboard. 
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In addition to the keys corresponding to the alphabetic and numeric 
characters that appear on the screen, the keyboard has 16 Program 
Function (PF) keys. By using the SHIFT key, a total of 32 PF key 
values can be obtained. 

Whenever the workstation is ready to accept input from either the 
keyboard or the PF keys, a cursor is shown on the screen. The cursor 
appears as a flashing bar under the character position where the next 
character typed will appear. The cursor (and thus the position of the 
next character) can be moved using the four cursor control keys, each 
of which is marked with an arrow indicating the direction in which it 
moves the cursor. 

At any time, certain keys are accepted for input, while others are 
not. For example, a program may prompt you to input certain numeric 
data. In this case, using the alphabetic keys is invalid. Any time 
an invalid key is pressed, either from the keyboard or the PF keys, 
the workstation alarm sounds, and the key is ignored. 


1.2.2 Using the PF Keys with Menus 

Most of the commands and options you enter to system programs are 
entered by means of the PF keys in response to menus . A menu is a 
list of possible commands or options displayed on the workstation 
screen by a program. Next to the description of each command is the 
number of one of the PF keys. You select commands by pressing the 
appropriate PF key. 

Communication through PF key response to menu screens is extensively 
used in VS system programs since it frees you from the necessity of 
typing many commands and remembering their syntactical arrangements. 
This allows programs to be highly interactive and self-documenting. 

You can also use PF keys in BASIC programs to control the sequence of 
program execution and to assign values to variables in the program 
(refer to Sections 6.4.3 and 7.5.3 for details). 


1.2.3 Logging On 

Before using the VS system, you must log on to the system by entering 
a valid user ID and password at the workstation. User IDs and 
passwords are assigned to authorized users by the system security 
administrator at each VS installation. After you complete the logon 
procedure, the Command Processor menu appears. 
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1.2.4 


The Command Processor Menu 


The Command Processor menu appears 
program or procedure is executing, 
program; examine and manage files, 
Section 1.3.2); examine the status 
variety of other functions. 


at your workstation if no other 
From this menu, you can run a 
libraries, and volumes (refer to 
of peripheral devices; or perform a 


1.3 THE VS OPERATING SYSTEM 

The VS Operating System consists of a set of programs managing the 
hardware and software resources of the VS. The operating system 
allocates processor time and memory space to user tasks, processes all 
input/output operations between your programs and disk or tape files, 
and maintains a security system to ensure that only authorized users 
can gain access to the system hardware, software, and data. 

The operating system also includes the Command Processor menu, 
language compilers (e.g., BASIC, PL/I, and COBOL), such program 
development aids as the Editor and Linker, File Management utilities, 
and various other utility programs. The programs supplied as part of 
the operating system are called system programs (as distinguished from 
those written by users, called user programs). 


1.3.1 The Data Management System (QMS) 

The Data Management System (DMS) consists of several programs that are 
part of the VS Operating System. These programs process all 
input/output transactions between you or system programs and data 
stored in files on magnetic disk or tape. DMS also controls the 
creation of new files. The operation of DMS is transparent in that 
you do not directly interact with DMS. When your program is running 
and needs to perform a file I/O operation, DMS is automatically called 
to perform the necessary operations; your program then continues 
executing with no direct involvement in the I/O operation. Many of 
the functions performed by DMS involve the complex internal 
housekeeping tasks required to insure that information stored in files 
remains properly organized for reliable and efficient access through 
all input/output operations. Refer to the VS Operating System 
Services manual for more details on DMS. 
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1.3.2 File Hierarchy 


A file is a collection of data stored on either magnetic disk or tape, 
identified by a file name. Groups of disk files are organized into a 
hierarchical structure with two higher levels: libraries and 
volumes. Groups of tape files are organized into volumes (there are 
no tape libraries). 

The most comprehensive unit in the file management hierarchy is the 
volume . A volume is an independent physical storage medium, such as a 
diskette, disk pack, or tape. The volume name provides a 
device-independent means of identifying physical storage units. Once 
a diskette, disk pack, or tape has been assigned a volume name, it can 
be mounted at any available drive unit and accessed by name, without 
reference to the address or physical characteristics of the disk or 
tape unit itself. 

Immediately belov; the volume in the disk hierarchy is the library . A 
volume can contain one or more user libraries, but a single library 
cannot continue onto a second volume. Each library contains one or 
more files (every disk file must be assigned to a library). The VS 
places no particular restrictions on the types of files placed in a 
library. You can use a single library for program and data files, or 
you can designate special libraries for each file type. The 
conventions governing library usage are completely determined at each 
individual installation, based on its particular needs and standards. 

Duplicate file names cannot be used within the same library, but they 
can be used in different libraries. Similarly, duplicate library 
names are not permitted on the same volume, but can be used on 
separate volumes. Duplicate volume names are allowed but not 
recommended. 

File and library names can contain up to eight characters. Volume 
names contain up to six characters. Each name must begin with an 
uppercase letter, a number, or one of the special characters $, #, 
or @. Subsequent characters can be any alphanumeric character, 
including the special characters. Embedded spaces are not allowed. 


1.4 VS BASIC PROGRAM DEVELOPMENT 


The VS central processing unit (CPU) hardware, like most digital 
computers, can directly execute only instructions written in machine 
language . Machine language consists of groups of electrical impulses 
represented as binary or hexadecimal (base 16) numbers. Machine 
language is cumbersome for programmers, and using it to program 
directly is tedious. 
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vs BASIC, on the other hand, is an extremely convenient and readable 
language in which to write programs, but the CPU cannot directly 
execute programs written in VS BASIC. In order for a BASIC program to 
be executed (or "run"), it must first be translated into machine 
language. This translation is accomplished by a large program called 
the VS BASIC compiler ; the translation process is called compilation. 

The VS BASIC compiler takes as input a file containing a program 
written in the VS BASIC language as described in this manual. Such a 
program is called a source program ; the file containing this program 
is a source file . As output, the compiler produces a file containing 
the machine language translation of the source program. This machine 
language program is called an object program ; this program is found in 
an object file . You can run the object program by using the RUN 
command (PFl) of the Command Processor menu. 

In summary, developing and executing a VS BASIC program consists of 
three steps (not including the logical design and coding of a program 
into BASIC instructions): 

1. Enter the BASIC source program from the workstation using the 
Editor. The source program is stored in the source file. 

2. The VS BASIC compiler compiles the source program to produce an 
object program, and the result is stored in the object file. 

3. The object program is run from the Command Processor menu. 

You can perform these steps separately by running first the Editor, 
then the VS BASIC compiler, and finally your object program, returning 
to the Command Processor menu after each step. The entire process can 
also be performed from the Editor, enabling you to compile and run 
programs directly from its Special menu. Section 1.4.1 describes the 
Editor in greater detail. Also refer to the VS Program Development 
Tools reference. Sections 1.4.1 and 1.4.2. summarize the process of 
creating and running a new BASIC program. 


1.4.1 The EDITOR 

To run the Editor, invoke the RUN command (PFl) from the Command 
Processor menu, type EDITOR for the program name, and press ENTER. 

The Editor first displays an Input Definition screen, requesting the 
following information: 

LANGUAGE — Type B or the word BASIC. 
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Source FILE, LIBRARY, VOLUME — If a new file is to be created, leave 
the file name blank. Names are assigned to new files after the text 
of the file has been entered, with the CREATE command (PF5). If an 
existing file is to be edited, enter its name and the names of the 
library and volume on which it is contained. LIBRARY and VOLUME may 
have default values set when this screen appears. You can change the 
default values by typing over the default responses. 

Object PLIBRARY, PVOLUME — Specify the library and volume names for 
any object program generated in this session. Note that no permanent 
object file is created until a permanent source file is compiled. 
PLIBRARY and PVOLUME may have default values (corresponding to OUTLIB 
and OUTVOL, respectively) set when this screen appears; you can change 
these values by typing over the default responses. 

Print File LLIBRARY, LVOLUME — Specify the library and volume names 
for compiler-generated print files. These fields default to SPOOLIB 
and SPOOLVOL, respectively, but can be modified. 

Debug PLIBRARY, PVOLUME — Specify the library and volume names for 
symbolic debug information files. PVOLUME defaults to your current 
OUTVOL value; the default value for PLIBRARY is generated by 
concatenating the user ID with DEBUG. These values can be modified by 
typing over the default responses. 

SCRATCH — Specify whether the Editor should automatically delete a 
file having the same name and location as a compilation output file. 
The default response, YES, automatically scratches the existing file; 
a NO response causes the Editor to request another file location or 
permission to delete the file. 

When all of the above information is typed in appropriately, press 
ENTER. 

The Editor next creates a work file for text editing. The editing of 
source text actually takes place in this temporary work file. To 
permanently store any text entered in the Editor, you must either 
create a new file of the edited text or, if an old file was used, 
replace the old text with the edited text. The original file is not 
altered until a replace is done, as all changes are made in the work 
file. Files are created and replaced using the CREATE (PF5) and 
REPLACE (PF6) commands from the Editor’s Special menu. 

The Editor then displays its normal menu, which contains functions for 
examining, entering, and editing source text. The most important 
functions are briefly explained here. More detail on these and 
explanations of the other functions can be found in the VS Program 
Development Tools . 
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PFl — DISPLAY — Display mode displays your file on the screen. The 
first time this command is used in an Editor session on an existing 
file, the file is displayed starting with the first line of text. 
Subsequent uses of this command return to displaying the file at the 
point where the last editing function was performed. While in Display 
mode, different portions of the file can be examined by using PF keys 
2 through 6. 

PF9 — MOD — Modify mode allows you to enter a new program, modify 
existing source lines, or add lines to the end of an existing program. 

PFll — INS — Insert mode allows text to be inserted in an existing 
program between lines, before the beginning of the program, or at the 
end. You can also enter a new program in Insert mode. Unlike the 
Modify mode, you can alter in place the line numbers supplied by the 
Editor. Before pressing PFll, position the cursor on the line after 
which the new line is to be inserted. 

PF12 — DEL — Delete mode allows you to delete text (either a 
specific line, a range of lines, or all lines) from the source file. 
Before pressing PF12, position the cursor on the first line to be 
deleted. 

PFl6 — MENU — Activates the Editor's Special menu. 

To enter lines of text for a new file, enter either Modify (PF9) or 
Insert (PFll) mode and simply type in the lines. Pressing ENTER sends 
the lines just typed to the system for processing. This must be done 
after every inserted line. In Modify mode, you can fill the screen 
with new lines before pressing ENTER. 

To return to Display mode from Modify or Insert modes, press PFl after 
the last line of text is entered (or, if in Modify mode, simply press 
ENTER). 

After entering the entire VS BASIC program, you can it in a disk file, 
compile it, or run it directly. All of these functions are performed 
from the Editor's Special menu. The Special menu is obtained by 
pressing PF16 from Display mode. 

The Special menu has 14 functions. The more important ones are found 
in the following list. Refer to the VS Program Development Tools for 
complete descriptions of all Special menu functions. 

PFl — DISPLAY — The Editor is returned to the point from which the 
Special menu was invoked. 

PF5 — CREATE — A new file of the edited text is generated. You are 
asked to supply file, library, and volume names and several optional 
pieces of information, including a retention period during which the 
file cannot be scratched. 




O 
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PF6 — REPLACE — The old input file is replaced with the new edited 
text. 

PF9 — RUN — An uncompiled program is compiled and run, or a compiled 
program is run. If the text has not already been successfully 
compiled in this Editor session since the last text entry was made, 

RUN invokes the VS BASIC compiler and Linker to compile the program, 
and then automatically runs the program (unless there are serious 
compilation errors). If compilation is not necessary, the program is 
run. 

PFIQ — COMPILE — The BASIC compiler and (optionally) the Linker are 
invoked, but the program is not actually run. 

PFll — ERRORS — A list of detected errors is displayed. If the 
default value of ERRLIST in the Compiler/Linker Options display was 
changed to NO, this list is not displayed, and is not accessible from 
the Editor. 

PF16 — EOJ — Editor processing is ended and control is returned to 
the Command Processor menu. 


NOTE 


You must specify an object file name, library, and volume whenever a 
permanent source file is compiled from the Editor, and PLIBRARY and/or 
PVOLUME were not set previously. If PLIBRARY and PVOLUME have been 
set, BASIC uses the file name of the source file as the file name of 
the object file. Specifying a file name that begins with ## causes a 
temporary file to be created. Such a file is automatically scratched 
at the end of the Editor session. 


1.4.2 The BASIC Compiler 

You can invoke the VS BASIC compiler from either the command processor 
by the RUN (PFl) command, or from the Editor by the RUN (PF9) or 
COMPILE (PFIO) commands on the Special menu. In either case, the 
compiler displays a list of options when it is invoked. 

Options 

Appendix B describes the compiler options in greater detail. The 
following five options are the most important. 

LOAD — Directs the compiler to produce an object program as output. 
Its default value is YES. If NO is typed, no object program is 
produced. (The code generation phase of the compiler is not run.) 
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SOURCE — Directs the compiler to produce a listing of the source code 
for the compiled program combined with a list of any compiler-detected 
errors. YES causes the listing to be produced; NO suppresses it. The 
default value is YES. 

SYMB — Directs the compiler to insert symbolic debug information into 
the object program, permitting subsequent use of the VS interactive 
symbolic debug facility when the program is run. You can remove 
symbolic debug information from a program using the Linker. The 
default value is YES. 

DFLOAT — Directs the compiler to perform all floating-point 
manipulations in the float decimal representation. A response of YES 
causes float decimal handling; the default response of NO causes float 
binary handling. Because the decimal floating-point format is not 
available on the VS80 or VS50, a response of YES on these machines 
results in an immediate error message. 

MINANS — Directs the compiler to use the rules for either the ANSI 
Standard or the VS BASIC Standard. The ANSI Standard is used when 
MINANS=YES, which also forces the SUBCHK and DFLOAT options to YES. A 
selection of MINANS=NO selects the VS BASIC Standard. MINANS=NO is 
the default. 

When all desired options have been selected, press ENTER. 


Input Definition 

The VS BASIC compiler now requests the name of the source file to be 
used as input, unless VS BASIC was invoked from the Editor. Enter the 
file name, along with the appropriate library and volume names. 


Output Definition 

If you specify LOAD = NO, and if the program passes the compiler's 
syntax check with no error of severity equal to or greater than the 
specified STOP level (refer to Appendix B), a name for the output file 
to be created containing the compiled (object) program is requested. 
Enter the file name, along with the names of the library and volume to 
which it will be assigned. You can also specify the following options: 

RECORDS — The number of records in the output file is determined 
automatically by the compiler based on the size of the input file. In 
general, you should not change this value. 
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RETAIN — During the specified retention period, the file cannot be 
scratched or renamed. Only the owner or a security administrator can 
change the retention period. If such protection is not deemed 
necessary, leave the RETAIN field blank. 

RELEASE — If RELEASE = YES, any space originally allocated to the 
object file but not actually used is released for use by other files. 
Otherwise, the space remains reserved for use by the object file. 

FILECLAS — The object file may be assigned to one of the VS file 
protection classes. Consult the system security administrator to 
determine in which protection class a particular file belongs. 

When the output file name and all options are defined, press ENTER. 

The message "BASIC Compilation of X in Progress" appears on the screen 
while the compiler runs from the Editor. The message "Program BASIC 
in Progress" is displayed if BASIC is run directly from the Command 
Processor menu. When compilation is complete, control returns to 
either the Command Processor menu or the Editor, depending on how the 
compiler was initially invoked. 

Return Code 


When compilation is complete, the first screen shown specifies a 
return code. The value of the return code indicates the severity of 
the errors found in the source program by the BASIC compiler. The 
possible return codes and their meanings are: 


Code 

0 

4 

6 or 8 
12 or 16 


Meaning 
No errors. 

Warning. 

Severe error (program probably will not run correctly). 
Terminal error (program will not run at all). 
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If production of the source listing is not suppressed, this listing 
and a list of compiler diagnostics (error messages) are printed on the 
selected printer, or directed to the print queue or your print library 
as specified by your PRNTMODE default (set with PF2 from the Command 
Processor menu; refer to the VS Programmer's Introduction for an 
explanation). All other optional listings and tables are similarly 
printed, queued, or filed. 

When the VS BASIC compiler is run from the Editor (by either the RUN 
(PF9) or the COMPILE (PFIO) commands from the Special menu), any error 
messages generated during the compilation can be viewed by pressing 
PFll from the Special menu. 

1.4.3 The LINKER Utility 

Use the VS Linker to perform the following functions: 

1. Link two or more object program modules or subroutines into a 
single executable program (refer to Section 6.5). 

2. Link library subroutines into a main program. 

3. Remove symbolic debug information from an object program. 

4. Replace one or more object program modules in a program. 

The Linker can be called whenever a program is compiled from the 
Editor. If the program is compiled using the BASIC compiler directly, 
the Linker must be run independently by invoking the RUN command from 
the Command Processor menu and typing in LINKER as the program name. 
See the VS Program Development Tools manual for more information on 
the Linker. 

Note that because of changes in the VS Operating System, you cannot 
link BASIC Version 2.3 programs to BASIC Version 3.2 or greater 
programs. The CVBASIC utility, described in Appendix I, converts 
BASIC Version 2.3 programs to BASIC 3.2 programs. 
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1.4.4 Running the Object Program 


To execute the compiled program, use the RUN command from the Command 
Processor menu. Press PFl to invoke this function, and type the BASIC 
object file name in the PROGRAM field. Type the appropriate library 
and volume names, and press ENTER to initiate execution of the program. 

The program continues to run until one of the following actions occurs: 

1. An END statement is executed. 

2. An "implied" END is reached because the physical end of the 
program is reached. 

3. A fatal execution error occurs. 

4. You interrupt execution with the HELP key. 

You can interrupt any program at any time using the HELP key. A 
modified Command Processor menu is then displayed. From this menu, 
you can cancel or continue to execute a program, enter debug 
processing, or perform other system commands. The debug processor is 
a powerful tool used to detect hard-to-find errors in the logical 
design of a program. The VS Program Development Tools manual 
discusses the debug processor. Note, however, that float decimal data 
currently cannot be examined or modified through the debug processor. 
Refer to Section 3.3 for details. 

If a program completes execution without interruption by errors or the 
HELP key, control returns to either the Command Processor menu or the 
Editor, depending upon how execution of the program was initiated. 
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CHAPTER 2 
PROGRAM FORMAT 


2.1 INTRODUCTION 

A VS BASIC source program consists of a series of instructions to the 
computer, called statements, which are written sequentially on 
numbered program lines. A program line can contain any number of 
statements. When a program is run, statements are executed 
sequentially in line number order. Multiple statements on the same 
line are executed left to right. 


2.2 STATEMENTS 

A statement usually begins with a word (called a "verb") that is 
typically an English verb, such as PRINT or ACCEPT. Any information 
that may be required to complete that particular statement follows the 
verb. For example, 

• RETURN forms a complete statement by itself. It signals the end of 
a subroutine. 

• LET X = 2 is an example of an assignment statement. In this case, 
the variable X is assigned a value of 2. 

• GOTO 40 transfers control to the given line number, in the case 40, 
and continues processing from there. 

• ^ is a BASIC verb but is not a complete VS BASIC statement by 
itself. 

• IF A = B THEN RETURN shows that another entire VS BASIC statement 
may follow the IF... verb. The IF statement causes some action to 
be taken depending upon whether or not a particular relation is true. 
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Verbs form part of a larger set of reserved words . Reserved words are 
sequences of alphanumeric characters that have some predefined meaning 
to the VS BASIC compiler. Reserved words never contain any embedded 
spaces. Since reserved words and their meanings are built-in parts of 
the VS BASIC compiler, you cannot use them as variable names or 
statement labels (refer to Section 6.2). Appendix A contains a 
complete list of VS BASIC reserved words. 

There are two types of VS BASIC statements: executable and 
nonexecutable. An executable statement specifies some action or a 
series of actions to be taken by your program at run time, such as 
assigning a value to a variable (LET statement), displaying or 
printing data on the workstation or printer (PRINT statement), or 
altering the order of program execution (GOTO statement). A 
nonexecutable statement provides information to the compiler at 
compilation time that may be required to generate the object program, 
such as the amount of storage to be allocated for certain variables 
(DIM statement) or the format to be used for printed output (FMT 
statement). 

The follovdng VS BASIC statements are defined as nonexecutable: 

COM 

DATA 

DEF 

DEF FN’ or DEFFN' 

DIM 

EJECT 

FMT or FORM 
% (Image) 

REM or * 

SELECT, when used for file I/O (i.e., SELECT # and SELECT POOL; refer 
to Section 8.3.1 for details) 

SUB 

TITLE 


2.3 LIME FORMAT 


Each line in a VS BASIC program can be up to 72 characters long, 
including leading and embedded spaces (the workstation screen is 80 
characters wide). Each character position is referred to by a column 
number, beginning with column 1 (the leftmost position). There are 
two choices for line format: one for the VS BASIC Standard and one 
for the ANSI Standard. 


2-2 Program Format 


When the program is compiled with the VS BASIC Standard rules, (as 
indicated by selecting the MINANS = MO compiler option), the first six 
columns of each line in a VS BASIC source file are reserved for a 
unique six-digit line number, leaving 66 columns (numbers 7 through 
72) for program statements. Columns 73 through 80 may be used as a 
program identifier. Any line containing an asterisk (*) in column 7 
is designated as a comment line and is ignored by the compiler (refer 
to Section 2.3.3). 

When the program is compiled with the ANSI Standard rules (as 
indicated by a selection of the MINANS = YES compiler option), line 
numbers are from one to six digits long and must be followed by a 
space. Program lines can be up to 72 characters long and may continue. 


NOTE 


When the Editor is used to create or edit BASIC source files, program 
lines are displayed on the workstation screen with an extra space 
inserted between column 6 (which contains the rightmost digit of the 
line number) and column 7 (the first column available for typing 
program text characters). This extra space is also inserted to 
increase readability when the BASIC compiler prints source file 
listings. Thus, on printed listings and in this manual, the character 
in column 7 of a line actually appears in the eighth physical print 
position on the paper. This extra space is not, however, included in 
the internally stored representation of a program line. 


2.3.1 Spacing 

Within a statement, the VS BASIC compiler uses spaces between strings 
of nonblank characters to distinguish the significant entities or 
"tokens" that comprise the statement. To avoid ambiguity, spaces must 
occur at certain places in a statement and must not occur at others. 
For example: 

100 FOR K = I TO J 500 FORK = ITOJ 

Both lines contain the same sequence of nonblank characters, and both 
are valid VS BASIC statements, but with completely different 
meanings. Line 100 is the beginning of a FOR...NEXT loop (refer to 
entries under FOR and NEXT in Part II). In this statement, FOR and TO 
are VS BASIC reserved words (refer to Section 2.2) and K, I, and J are 
variable names. Line 500 is an assignment statement (an "implied" LET 
statement) in which both FORK and ITOJ are variable names. The 
statement assigns the value of ITOJ to the variable FORK. 
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In general, spaces usually occur in a statement so as to eliminate 
ambiguities in the interpretation of the statement. In particular, 
observe the following rules: 

1. All VS BASIC reserved words, including verbs, must be spelled 
exactly as shown in Appendix A, with no embedded spaces. GOTO and 
GO TO are both valid and equivalent forms for the unconditional 
branch statement. GOSUB and GO SUB are also both valid and 
equivalent statements. 

2. Literals (refer to Section 3.4.1) can contain any combination of 
blank and nonblank characters; a literal, however, cannot contain 
its delimiter. 

3. No embedded spaces are allowed within variable names (refer to 
Section 3.3.3 for rules of forming variable names). 

4. No embedded spaces are allowed v/ithin statement labels (refer to 
Section 6.2 for rules governing formation of statement labels). 

5. No embedded spaces are allowed in numbers (either line number 
references or constants). 

6. One or more spaces are required between any reserved word, 
variable name, or statement label and any other reserved word, 
variable name, or statement label. 

7. Spaces are ignored immediately before and after arithmetic 
operators (refer to Section 4.2.2), relational operators (refer to 
Section 4.2.3), and punctuation marks. 


2.3.2 Multiple Statement Lines 

A program line can contain any number of statements. A line 
containing no statements is called a null line and consists simply of 
a line number followed by 74 spaces. If a program line contains more 
than one statement, a colon (:) is used to separate one statement from 
the next, except following Image {%), TITLE, or EJECT statements (each 
of these statements is always considered as extending to the end of 
the line on which it occurs). Additionally, the colon does not 
terminate a REM statement when the compiler option MINANS = YES is 
selected. For example: 

400 LET TWEEDLEDUM = I : LET TWEEDLEDEE = J : LET ALICE$ = "CONFUSED" 

400 REM ALL CHARACTERS OF THIS LINE ARE CONSIDERED : COMMENTS 

You can insert a null statement anywhere in a line by using one colon 
immediately after another, or two colons separated only by blanks. 
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2.3.3 Continuation of Statements 

You can continue statements beyond column 72 of a line by inserting an 
exclamation point (!) in coliimn 72 of the line to be continued. For 
example, 

400 LET R0CK= I 

500 4 

is equivalent to: 

400 LET R0CK=4 

Although a statement can begin on one line and end on another line, 
reserved words, constants, variable names (refer to Section 3.3.3), 
statement labels (refer to Section 6.2) and line number references 
cannot be split between lines. For example, 

400 LE ! 

500 T ROCK = 

is not a valid statement. You can, however, split literal strings 
(refer to Section 3.4.1). 

There is no limit to the number of lines that you can use to contain a 
single statement, nor to the number of statements that can occupy a 
single line. 

2.3.4 Sequence of Execution 

Execution of a VS BASIC program always proceeds in line number 
sequence from the lowest-numbered line through the highest-numbered 
line, unless the normal sequence of execution is altered by a program 
branch instruction. Program branch instructions include the 
following: FOR...NEXT loops, GOTO, GOSUB, GOSUB', CALL, RETURN, and, 
in certain cases, IF...THEN...ELSE. Program branch instructions are 
discussed more fully in Chapter 6 and Part II. 


2.4 PR(X3RAM DOCUMENTATION 


2.4.1 Comments 

As an aid to program documentation, it is often useful to insert 
explanatory comments into the text of a program. Such comments must 
be distinguished in some way so that the compiler does not attempt to 
interpret them as executable program statements. VS BASIC provides 
three methods of inserting comments into programs: 
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1. When the program is compiled with tne rules for VS BASIC (i.e., 
when the compiler option MINANS = NQ is selected), any line that 
has an asterisk (*) in column 7 (the'^f.irst column following the 
six-digit line number) is treated as a comment line. The entire 
line is disregarded by the compiler and can contain any 
combination of printing characters. Comment lines of this form 
cannot be continued (as described in Section 2.3.3). For example, 

100000* DIRAC WAS A QUANTUM MECHANIC 

When the program is compiled with the rules for the ANSI Standard 
(i.e., when the compiler option MINANS = YES is selected), the 
asterisk (*) as a comment line designator must appear in the 
position following the blank that follows the line number. For 
example, 

100000 * DIRAC WAS A QUANTUM MECHANIC 

2. Any statement beginning with the reserved v/ord REM is treated as a 
comment (REMark). REM statements are ignored by the compiler and 
can appear wherever any other statement appears (refer to Section 
2.3). A REM statement can contain any combination of printing 
characters except a colon (;) when the compiler option 

MINANS = NO is selected. In this case the colon is considered to 
be a statement terminator and can be used to separate a REM 
statement from another statement on the same line. REM statements 
can be continued by using the exclamation point in column 72, as 
discussed above. For example, 

100 REM CATASTROPHE THEORY SIMULATION OF CANINE BEHAVIOR 

560 DST=SIN(A)/COS(B) :REM CHECK FLAGS :IF FLAG1=1 THEN 1200 

3. You can insert a comment by enclosing it between the symbols /* 
and */. Comments delimited in this way (called "enclosed 
comments") can be inserted on a line alone, before, after, or 
between statements on a line, or within a statement. Enclosed 
comments within statements can occur before or after (but not 
within) reserved words, variable names, statement labels, line 
number references, numbers, literals, functions, operators, and 
punctuation marks. All characters that follow the /* symbol 
(including subsequent occurrences of /*) are treated as part of 
the comment until the */ is encountered. Enclosed comments can 
span multiple lines. Examples: 

700 EXCH$ /* TELEPHONE EXCHANGE */ = STR(PH0NENUMBER$,4,3) 

1100 /* COMMENTS OF THIS FORM MAY EVEN EXTEND 
1200 OVER MANY LINES, AND MAY CONTAIN ANY SERIES 
1300 OF CHARACTERS... !@#$%^&*()... BUT MUST 
1400 END WITH THE STAR-SLASH SYMBOL: */ 
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2.4.2 Compiler Directives 






/ 

VS BASIC also lets you use the TITLE and EJECT statements to control 
the pagination and titling of the program source listing produced by 
the compiler. TITLE and EJECT both belong to a set of statements 
known as compiler directives . Lines that contain TITLE and EJECT 
directives are not printed in source listings generated by the 
compiler, although their respective effects on the form of the listing 
do appear, as described in the following text. TITLE and EJECT lines 
are, however, shown by the VS Editor and file display programs. 

A TITLE statement must be the only statement on a line. When a TITLE 
statement is encountered during compilation, the compiler skips to the 
top of the next page of the output listing and titles that page with 
the line of text specified in the TITLE statement. All subsequent 
pages of the listing are also printed with the specified title until 
another TITLE statement occurs. All characters, including any 
occurrence of a colon {:) or an exclamation point (!), following the 
reserved word TITLE on the same line are regarded as part of the 
title. Mote that this means that a TITLE line cannot be continued by 
using the exclamation point (!) convention described in 
Section 2.3.3. For example, to print the title PART I: VARIABLE 
INITIALIZATION SECTION at the top of a page of source listing, one 
would use 

500 TITLE PART I: VARIABLE INITIALIZATION SECTION 

The EJECT statement, which must also appear as the only statement on a 
line, causes the compiler to skip to the top of the next page of the 
source listing and to print the most recently specified title at the 
beginning of the page. All text following the word EJECT on the same 
line is ignored. 
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CHAPTER 3 
DATA FORMATS 


3.1 INTRODUCTION 

Programs written in VS BASIC are capable of processing both numeric 
and alphanumeric data. Numeric data can be stored and processed 
either in integer format or in floating-point format. Alphanumeric 
information can be stored and manipulated as single characters or as 
strings of characters. In addition, individual bits within 
alphanumeric data can be manipulated using logical operators. 

Both numeric and alphanumeric data can be processed singly, as 
constants or scalar variables, or in sets of arbitrary size called 
arrays , which can be referred to by a single name. Individual 
elements of an array can also be processed as scalar variables. 

This chapter describes the types of data VS BASIC processes and the 
formats used for representing data. Chapters 4 and 5 discuss the 
various operations that can be performed on data. 


3.2 CONSTANTS, VARIABLES, RECEIVERS, AND EXPRESSIONS 


A constant is an item of data whose value is fixed in a program and 
does not change during program execution. In contrast, a variable is 
an item of data that does not have a fixed value and can be assigned 
different values during program execution. A constant appears in a VS 
BASIC program as a number or a literal (refer to Section 3.4.1). Each 
variable is represented by a unique variable name , which is used to 
name that area in storage holding the value of the variable. For 
example, in the statement 

CIRCUMF = 3.14159 * DIAM 
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CIRCUMF and DIAM are variable names, and 3.14159 is a constant. This 
particular statement multiplies the value of the variable DIAM by the 
constant 3.14159 (the asterisk {*) is the symbol used to indicate 
multiplication in BASIC). The product is stored in the variable 
called CIRCUMF. The different types of constants and variables VS 
BASIC recognizes and the rules for naming variables are described in 
Section 3.3.3. 

A receiver is a variable into which data can be stored. Receivers are 
used wherever a value is "received," e.g., on the left side of a LET 
statement, in the argument list of a READ statement, etc. All 
variables are receivers; for numeric data, all receivers are 
variables. Alphanumeric receivers (or simply alpha receivers) include 
alphanumeric variables and a few special functions. Refer to Section 
5.4.2 for a list of all alpha receivers. 

An expression is either a constant, a variable, a function, or some 
combination of these connected by operators. When a statement 
containing an expression is executed, the indicated operations and 
functions are performed to yield a single value for the expression. 
Functions and operators are constructs that specify particular 
operations to be performed on one or more expressions. Separate 
operators and functions exist for manipulating numeric and 
alphanumeric data. (Refer to Chapters 4 and 5.) An expression can 
contain either numeric or alphanumeric data, but the two data types 
cannot be combined in one expression. 


3.3 NUMERIC DATA 

VS BASIC recognizes two types of numeric data; floating-point and 
integer. The types are clearly distinguished in VS BASIC syntax, 
require different amounts of internal storage, are represented 
differently in internal format, and have a different range of 
allowable values. In addition, VS BASIC supports two floating-point 
representations: float binary and float decimal. However, when the 
compiler option MINANS = YES is selected, all floating-point values 
are processed as float decimal. The float decimal representation is 
not available on VS50 and VS80 systems. 

Integer data, which is used to represent "whole" (i.e., nonfractional) 
numbers, is stored in four bytes of memory. Thus, the integer data 
type can represent values ranging from -2,147,483,648 (-2^^) to 
2,147,483,647 (2^*-l). 
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Float binary data is stored as a hexadecimal fraction between 0 and 1, 
a binary exponent of base 16, and a sign. The float binary 
representation requires eight bytes of storage: one byte for the sign 
and exponent and seven bytes for the fraction. Since a digit in the 
hexadecimal representation requires four bits of storage, float binary 
values can contain up to 14 digits of precision. The maximum 
magnitude for float binary values is approximately 7.2 x 10^^; the 
minimum magnitude is approximately 5.4 x 10"^^. Consult the VS 
Principles of Operation for details on the float binary representation. 

Float decimal data (not available on VS50 and VS80 systems) is stored 
as a decimal fraction between 0 and 1, a binary exponent of base 10, 
and a sign. The float decimal representation requires eight bytes of 
storage: one byte for the sign and exponent, and seven bytes for the 
fraction. Since a decimal digit requires four bits of storage, float 
decimal values can contain up to 14 digits of precision. The maximum 
magnitude for float decimal values is 9.9999999999999 x 10®^; the 
minimum magnitude is 1 x 10'®^. Consult the VS Principles of 
Operation for details on the float decimal representation. 


NOTE 


A single module must perform all floating-point operations in either 
the float binary or the float decimal representation. The type of 
representation is selected through the DFLOAT compilation option, 
described in Section 1.4.2 and Appendix B. If two modules with 
different floating-point representations are linked, float data in one 
module must be converted to the other representation before access by 
the other module. The CVDQ and CVQD subroutines, described in Part 
II, interconvert variables in the float binary and float decimal 
representations. If two modules using different floating-point 
representations do not share floating-point data, no conversion is 
required. 
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Each type of numeric data has its particular advantages and 
disadvantages. Integer calculations are fast and precise; however, 
integer data cannot represent fractional or very large or very small 
values. Float binary calculations can manipulate a wider range of 
values than the integer or float decimal data type, but lose precision 
in the conversion to and from the hexadecimal representation (refer to 
Appendix C for more information). Float binary calculations are also 
slower than integer calculations. Float decimal calculations can 
manipulate a wider range of values than the integer data type with no 
loss of precision; however, float decimal operations are slower than 
float binary or integer calculations. A program using the float 
decimal representation is also larger than an identical program using 
float binary values. It is up to you to determine the best numeric 
representation for a particular application. 

VS BASIC allows complete freedom to mix floating-point and integer 
data (but not float binary and float decimal data) in arithmetic 
expressions and assignment statements. Expressions containing both 
integer and floating-point data are called mixed-mode . Section 4.5 
discusses these expressions. 


3.3.1 Floating-Point Constants 

A floating-point constant can be a positive or negative number of up 
to 15 digits. Fifteen digits can be specified for float binary 
constants because the 14 hexadecimal digits of the internal 
representation can evaluate to more than 14 decimal digits. For float 
decimal values, the fifteenth digit is used to round the value of the 
fourteenth digit. The compiler issues a warning when it encounters a 
floating-point constant with more than 15 digits in the source 
program. Only the first 15 digits, excluding leading zeros, are used 
by VS BASIC statements or functions. 


NOTE 


The compiler processes the first 15 digits of significance for a 
floating-point constant but scans the constant length for correct 
generation of the exponent. Thus, 12345678901234567890 generates 
1.23456789012345E19. 


A float binary constant can range from zero or approximately 
+5.4 X 10”^® to +7.2 X 10^^. Float decimal constants can range 
from zero or approximately +1 x 10"®^ to +1 x 10®^. 
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You can express very large or very small floating-point numbers in 
exponential form. Exponential form corresponds to standard 
"scientific notation" in which numbers are written as a decimal with 
one digit to the left of the decimal point, multiplied by some power 
of ten. Since the superscripts needed to write numbers in such 
notation cannot be easily represented on a keyboard device, a number 
in exponential form is represented as a decimal (usually with one 
digit to the left of the decimal point), immediately followed by the 
letter E, followed by an exponent representing a power of ten. The 
exponent must be an integer and can have a sign; if no sign is given 
for the exponent, it is assumed to be positive. Leading zeros can be 
omitted. Numbers in exponential form contain no embedded spaces 
between the decimal, the letter E, and the exponent. For example: 


Long Form Scient i fic Notation 


Floating 
Point Constant 


45000000 4.5 x lO" 

.00000045 4.5 x 10 ^ 

37234.123 3.7234123 x lO*" 


4.5E07 

4.5E-7 

3.7234123E+04 


The following are examples of valid floating-point constants in BASIC: 
4, -10, 1432443, -7865, 24.4563, -3E2, 2.6E-27 


The following are examples of invalid floating-point constants in 
BASIC: 


8.7E5.8 Not valid because of the decimal point in the exponent. 

.87E-99 Not valid because it is less than 5.4E-79 (float binary) 

and lE-66 (float decimal). 


103.2E99 Not valid because it is greater than 7.2E75 (float 
binary) and 1E63 (float decimal). 

103.2E70 Not valid in the float decimal representation because it 
is greater than 1E63; valid in the float binary 
representation. 
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3.3.2 Integer Constants 


An integer constant can range from -2,147,483,648 to 2,147,483,647 
(the decimal equivalent of the range of binary numbers that can be 
represented with 32 bits) and must, as its name indicates, be an 
integer. An integer constant is denoted by a percent sign {%) 
following the constant. Thus, 4% is an integer, and 4 is a 
floating-point number. The percent sign for numeric constants is only 
permitted for numbers or variables actually contained in the source 
file. Therefore, numbers given to the program during execution (i.e., 
from the workstation or data file, or converted from an alpha 
expression) must be given in floating-point form (i.e., without the 
percent sign). 


3.3.3 Numeric Variables 

You can use numeric variables to reference numeric data stored in 
memory. Unlike constants, you can assign variables new values during 
execution by a variety of different statements. Each variable name in 
a program is associated with an area in memory used to contain the 
value of that variable. Numeric variables are initialized to zero by 
the compiler. 

As is the case with constant data values, VS BASIC processes scalar 
variable values as either integers or floating-point numbers. All 
scalar floating-point variables are eight bytes in length, while all 
scalar integer variables are four bytes in length. 

Within the floating-point and integer data types, VS BASIC variable 
numeric data can be referred to as either scalar variables or array 
variables. The two kinds of variables differ in the syntax rules that 
apply to them and in their storage requirements. A numeric scalar 
variable contains a single numeric value. An array variable, on the 
other hand, contains one or more values, or "elements," all of which 
can be referenced by a single name that can be manipulated either 
collectively or individually. Section 3.5 discusses array variables 
in more detail. 

It is important to note the differences between integer and 
floating-point calculations. Refer to Section 3.3 and Appendix C for 
details. 
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Each variable in a program is referred to by an arbitrary and unique 
variable name which you choose. A variable name can be any string of 
up to 64 letters, digits, and underscores, provided that the first 
character is a letter and that the string is not a VS BASIC reserved 
word (refer to Section 2.2 and Appendix A). Numeric variables are 
designated as integer data type by appending a percent sign {%) to the 
end of the variable name. Any numeric variable that does not have a 
percent sign as the last character of its name is treated as a 
floating-point variable. The following examples are valid numeric 
variable names: 


Floating-Point 

N 

CAT 
PART 2 


Integer 

MOUSED 

FIRST 3 LINES^ 


The following examples are incorrect variable names; 


Variable Name 


Reason 


2ND_PART 
LINE COUNTS 

LAST %ILE 


The first character must be a letter. 

Names cannot contain spaces. COUNTS 
alone is a legal variable name. 

The percent sign is legal only at the 
end of a variable name. 


Note that a floating-point variable name and an integer variable name 
always identify different variables, even if the names are identical 
exclusive of the percent sign (%) (i.e., the letters, digits, and 
underscores). For example, INFUNDIBULUM and INFUNDIBULUM^ identify 
two different variables, one floating-point and one integer, and both 
can be used to refer to different items of data in the same program 
without ambiguity. 
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3.4 


ALPHANUMERIC DATA 


In addition to its ability to manipulate and operate upon numeric 
data, VS BASIC also provides the capability of processing information 
in the form of alphanumeric character strings. A character string is 
a sequence of characters treated as a unit. A character string can 
consist of any sequence of keyboard characters, including letters A 
through Z, digits 0 through 9, and special symbols. Character strings 
are represented in a program as literal strings (the alphanumeric 
equivalents of numeric constants), or as the values of alphanumeric 
string variables. Characters not found on the keyboard can be 
represented as hexadecimal ASCII codes. Typical examples of uses of 
character strings are names, addresses, and report headings. 

Note that alphanumeric data cannot be operated upon by numeric 
functions or operators. A separate set of operators and functions 
exists for manipulating alphanumeric data. VS BASIC also provides 
functions that convert alphanumeric data to numeric form and vice 
versa. Refer to Section 9.1 for details. 


3.4.1 Literals (Alphanumeric Constants) 

The value of an alphanumeric data item that is a fixed constant in a 
source program is called a literal or a literal string . You can write 
a literal string either by enclosing the needed sequence of characters 
in quotation marks or by specifying the hexadecimal ASCII codes of the 
characters in the literal with the HEX function. 

One type of quoted alphanumeric literal string is a sequence of 1 to 
255 characters enclosed in double quotation marks ("..."). Any 
uppercase or lowercase keyboard character except the double quote 
character can appear in a double-quoted literal. Literal strings can 
be used to specify messages, headings, or titles to be output to some 
device (e.g., workstation or printer) by any of several output 
statements. For example, 

PRINT "Last Page="; LPG 

In this case. Last Page= is a quoted literal that will print exactly 
as it appears. LPG is the name of a floating-point variable whose 
value will print following Last Page=. 

A second type of quoted literal string is available for specifying 
lowercase characters. The literal string is entered with uppercase or 
lowercase characters enclosed in single quotes ('...'). The single 
quotes indicate that the uppercase letters are to be treated as 
lowercase by the system. For example, 

PRINT "J";'OHN';" D";'OE' 
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results in the output 






John Doe (if device is capable of printing lowercase letters) 
or 

JOHN DOE (if device only prints uppercase letters) 

Mote that any uppercase characters within single quotes are also 
converted to lowercase. For example, 

PRINT 'John Doe' 

results in the output 

john doe (if device is capable of printing lowercase letters) 
or 

JOHN DOE (if device only prints uppercase letters) 

Any character is valid in a lowercase literal string except the single 
quote character ('). A single quote literal string can contain double 
quotes, and vice versa. 

When you select the compiler option MINANS = YES, a null literal 
containing zero characters, is permitted. Because alphanumeric 
variables are padded with null characters, blanks are significant. 

For example, 

090 LENC'ABC ") 

100 A$="ABC PRINT A$; "DEF" 

results in the output 

ABC DEF 

Additionally, literals in a DATA statement need not be enclosed in 
quotation marks when the compiler option MINANS = YES is selected, as 
leading and trailing blanks are ignored.^ 

You can also write literals using the HEX function. In this form, 
characters in the string are specified by their hexadecimal ASCII 
codes (sometimes called hex codes). Each printing character (and each 
of the nonprinting workstation control characters called Field 
Attribute Characters) can be represented by a corresponding ASCII code 
composed of two hexadecimal digits (0 through 9 and A through F; refer 
to Appendix F for a list of the ASCII hexadecimal codes). 
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In a HEX literal, the ASCII hexadecimal codes are placed in 
parentheses following the word HEX. For example, 

PRINT HEX(414243) 

prints the string ABC, since 41, 42, and 43 are the hexadecimal codes 
for the first three letters of the alphabet. This statement is 
equivalent to PRINT "ABC". HEX(4120422043) corresponds to the same 
sequence of letters, with spaces (ASCII code 20) between them. Any 
legal hexadecimal code may be specified in a HEX literal string. You 
should, however, be aware of the special use of hexadecimal codes 80 
through FF (refer to Section 7.3.3). 

You can also assign literal strings as values to alphanumeric 
variables. Section 5.2 discusses assignment and other alphanumeric 
operations. 


3.4.2 Alphanumeric Variables 

Alphanumeric character strings can be stored and processed in an 
alphanumeric string variable (or simply "alpha variable"). Values 
stored in alpha variables can be stored and processed singly, as 
scalar variables, or in groups, as array variables. Alphanumeric and 
numeric arrays are discussed in Section 3.5. The following discussion 
applies to alphanumeric scalar variables. 

Alpha variable names, like those of numeric variables, are sequences 
of up to 64 letters, digits, and underscores, provided that the first 
character of the name is a letter and that the name is not a VS BASIC 
reserved word (refer to Appendix A). Alpha variable names are 
distinguished from numeric variable names by a dollar sign ($) 
appended to the end of the variable name. For example, the variable 
name THING refers to a floating-point numeric variable; THING$ refers 
to an alphanumeric variable. Similarly, ITEM% is an integer variable; 
ITEM$ is an alpha variable. A numeric variable and an alpha variable 
are separate and independent entities, even if they have the same name 
exclusive of the dollar sign. 

An alphanumeric variable identifies a unique location in memory 
reserved for the storage of alphanumeric data. The compiler reserves 
space for each variable during compilation, at which time the program 
is scanned for all variable references. The number of characters that 
can be stored in an alpha variable depends on how much space is 
reserved for that variable during compilation. Each character 
requires one byte (eight bits, or binary digits) of storage. You can 
specify the amount of space reserved for each variable using a DIM or 
COM statement. 
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For example, 

DIM WORD$ 10, LINE$ 80 

COM HORSE$ 10, COW$ 17 

reserves 10 bytes of storage for W0RD$, 80 bytes for LINE$, 10 bytes 
for H0RSE$, and 17 bytes for COW$, the latter two in the common 
storage area. (For an explanation of common storage, refer to 
Section 6.5.4.) An alpha scalar variable can be specified as having 
any length between 1 and 256 characters (bytes). An alpha variable 
cannot appear more than once in DIM or COM statements in a program 
because it is then declared more than once and will not compile. If 
you do not explicitly dimension an alpha variable in a DIM or COM 
statement, the compiler automatically reserves 16 bytes for the 
variable. The DIM and COM statements are both also used for 
dimensioning arrays (refer to Section 3.5.2). The COM statement is 
also used for placing variables of any type in common storage (refer 
to Section 6.5.4 and the COM statement entry in Part II). 


NOTES 


1. Any alpha variable that has not had some other value assigned to it 
is defined as being filled with blanks (ASCII code HEX(20)). 

2. When the compiler option MINANS = YES is selected, any alpha 
variable that has not been assigned a value with a DIM statement is 
assigned 18 bytes of space as a default and is initialized with 
nulls rather than blanks. An empty alpha variable has the length 
of zero. During assignments, alpha variables are padded with nulls. 


The length of an alpha variable or alpha array element specified in a 
DIM or COM statement is called its "defined" length. In many cases, 
however, the character string stored in an alpha variable does not 
occupy the entire defined length. When the compiler option 
MINANS = NO is selected, the last character of an alpha variable is 
normally taken to be the final nonblank character (except when the 
value is all blanks, in which case the value is treated as one 
blank). Hence, trailing blanks generally are not considered part of 
the value of an alpha variable. For example, 

100 A$ = "ABC 

200 PRINT A$;"DEF" 

results in the output 

ABCDEF (The trailing blanks of A$ are not printed.) 
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The character string stored in an alpha variable is called the current 
value of the alpha variable, and its length, up to the first trailing 
blank, is called the current length (or actual length) of the 
variable. When the compiler option MINANS=NO is selected, the length 
function, LEN, determines the current length of an alpha variable. 

For example, 

100 A$="ABCD 
200 PRINT LEN(A$) 

results in the output 

4 (LEN does not consider trailing blanks to be part of the value of 
an alpha-variable.) 

Most alphanumeric operators and functions operate on the current value 
of an alpha variable. In some cases (e.g., ACCEPT and DISPLAY 
statements), however, the entire defined length of the variable may be 
used. It is therefore important to understand the distinction between 
defined length and current length. 

NOTE 


If the defined length of an alpha variable is greater than necessary 
for storing the value of a given alpha expression, the variable is 
padded with blanks (ASCII code HEX(20)) when the value is assigned and 
the compiler option MINANS = NO is selected, and nulls (HEX(OO)) when 
MINANS = YES, 


3.5 ARRAY VARIABLES 

An array variable is a collection of scalar variables identified by a 
common name. Each scalar variable contained in the array is called an 
element of the array, and can be identified by specifying the array 
name followed by a subscript or pair of subscripts, which locate the 
element within the array. Arrays, like scalar variables, can hold 
floating point, integer, or alphanumeric data. A single array cannot 
hold values of more than one type. The names of array variables are 
formed in the same way as the names of scalar variables (a sequence of 
1 to 64 letters, digits, and underscores, as described in 
Section 3.3.3. Names of integer arrays must end in the percent sign 
{%) and those of alpha arrays must end in the dollar sign ($)). The 
one additional restriction on array names is that they cannot begin 
with the characters FW. 
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NOTE 




Any attempt to use a name beginning with FN for an array will result 
either in an error message at compilation time or in a logically 
incorrect object program. When MINANS is set to YES, any name 
beginning with FN and containing parentheses is interpreted by the 
compiler to refer to a user-defined function (refer to Section 4.4.2). 




In general, any reference to an array variable must consist of the 
array name followed by parentheses. If the parentheses enclose an 
expression or a pair of expressions, the expressions are interpreted 
as the subscripts of a particular element in the array. For example, 
the fifth element in floating-point array M() can be specified as 
N(5); BOX$(K) refers to the K-th element of the alpha array BOX$(). 
Note that the subscript is enclosed in parentheses immediately 
following the array name. In situations in which the entire array 
(rather than a particular element of the array) is to be referenced, 
you must follow the array name by empty parentheses, e.g., N() or 
BOX$(), to form an "array-designator." The array name alone (e.g., N 
or BOX$) is used only in special matrix statements (e.g., MAT INPUT 
and MAT PRINT). 


Since scalar variables are different from array variables, the same 
name (i.e., the same sequence of letters, digits, and underscores) can 
be used both as a scalar variable name and as an array variable name. 
Thus N() designates an array variable, while N names a scalar 
variable, except in a matrix statement. In any statement except a 
matrix statement (refer to Section 9.2), the array must always be 
referenced with an array-designator to indicate an array rather than a 
scalar variable. For example. 


WHALE 
WHALE% 
WHALE() 
WHALER() 
WHALE$ 
WHALE$() 


Identifies a floating-point scalar variable. 
Identifies an integer scalar variable. 
Identifies a floating-point array. 

Identifies an integer array. 

Identifies an alphanumeric scalar variable. 
Identifies an alphanumeric array. 


To minimize the chance of confusion, however, using the same name for 
scalar and array variables in a program is not recommended. 
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In addition, when the compiler option MINANS = YES is selected, arrays 
and scalars of the same name are not permitted in the same program. 

The array base can optionally start with zero or one, allowing ranges 
of 0-N rather than 1-N. Also, an array need not be explicitly 
dimensioned, as the number of dimensions is taken from its first use. 
All floating subscripts are rounded rather than truncated. The 
default base is zero. 


3.5.1 One-Dimensional and Two-Dimensional Arrays 

Array variables can be either one-dimensional or two-dimensional. A 
one-dimensional array is a list of all variables identified by the 
same name. A two-dimensional array is a table of variables all 
identified by the same name. 

A one-dimensional array can be thought of as a list or column of 
variables (elements), each occupying its own slot, or row, in the 
column. Consider, for example, the representation of array DWARF{) in 
Figure 3-1. 


DWARF{) 


Row 

1 

DWARF(l) 

Row 

2 

DWARF(2> 

Row 

3 

DWARF{3) 

Row 

4 

DWARF{4) 

Row 

5 

DWARF(5) 


Figure 3-1. The One-Dimensional Array DWARF() 


Note that DWARF() contains a total of five elements and that each 
element is identified by specifying its row. For example, element 
DWARF(3) is located in row 3. 

One-dimensional arrays are also called lists, vectors, column vectors, 
and, since each element is identified by a single subscript, 
singly-subscripted arrays. 

The scheme in Figure 3-1 can be generalized to contain two or more 
columns. When this is done, the result is a two-dimensional array. A 
two-dimensional array can be thought of as a table consisting of two 
or more columns of elements. Consider, for example, the 
representation of the two-dimensional array HOBBITO in Figure 3-2. 


3-14 Data Formats 





HOBBIT() 




Column 1 

Column 2 

Column 3 

Row 

1 

HOBBIT(1,1) 

HOBBIT(1,2) 

HOBBIT(1,3) 

Row 

2 

HOBBIT(2,1) 

HOBBIT(2,2) 

HOBBIT(2,3) 

Row 

3 

HOBBIT(3,1) 

HOBBIT(3,2) 

HOBBIT(3,3) 

Row 

4 

HOBBIT(4,1) 

HOBBIT(4,2) 

HOBBIT(4,3) 

Rov/ 

5 

HOBBIT(5,1) 

HOBBIT(5,2) 

HOBBIT(5,3) 


Figure 3-2. The Two-Dimensional Array HOBBIT() 

Note that HOBBIT{) consists of three columns of elements, with five 
rows in each column, for a total of 15 elements. In this case, it is 
not sufficient to identify each element by its row, since the element 
may be in column 1, column 2, or column 3. A second subscript is 
required to identify the column. The convention followed when 
referencing a particular element in a two-dimensional array is always 
to specify the row first, and then the column. Thus HOBBIT(3,2) 
identifies the element in row 3 and column 2. 

Two-dimensional arrays are also called tables or matrices, and, 
because each element is identified by a pair of subscripts, 
doubly-subscripted arrays. 

Elements in an array can be referred to by subscripts that are legal 
BASIC expressions. Thus JIM(N) refers to the N-th element of array 
JIM() for whatever value N has at the time of execution. This ability 
to reference an array by a variable subscript is one of the useful 
features of arrays, since it can eliminate a considerable amount of 
repetitive coding. 

For example, the following three statements 

100 FOR I = 1 TO 50 
200 PRINT JIM(I) 

300 NEXT I 

cause the first 50 elements of array JIM() to be printed with 
considerably less coding than 50 consecutive PRINT statements. 
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NOTE 


If the value of an expression used as a subscript is not an integer at 
run time, the value of the expression is truncated and the integer 
value is used as the subscript when the compiler option MINANS = NO. 
When the compiler option MINANS=YES is selected, the value of the 
expression is rounded. 


3.5.2 Dimensioning an Array 

When a program is compiled, the BASIC compiler reserves storage space 
for each variable. To do this, the compiler must know how much space 
to allocate for each variable. Since arrays can be either one- or 
two-dimensional and can contain varying amounts of data, you must tell 
the compiler how much space to reserve for each array in a program; 
that is, the array must be dimensioned . An array is dimensioned by 
specifying whether it has one or two dimensions and how many rows (and 
columns, if two-dimensional) are in the array. Dimension information 
is specified using either the DIM (dimension) or COM (common) 
statement. For example, to allocate space for a one-dimensional 
integer array of 10 elements named VEGETABLE^(), write 

DIM VEGETABLES(10) 

If VEGETABLES() is to be used by more than one program or subprogram 
running together, use COM instead of DIM. 

You can use DIM and COM statements to define any number of arrays of 
any type, as long as each array is separated from the one following it 
by a comma. When using DIM or COM to dimension an alpha array, the 
length of each element in the array can be specified as an integer 
immediately following the right parenthesis. 

For example, 

DIM NAME$(500)10, CITY(IOO), STATE(5,10) 

COM CODE$(20,10)5, ZIPS(IOOO), COUNTS 

defines a 500-element, one-dimensional, alphanumeric array (NAME$()) 
where each element is 10 bytes long; a 100-element one-dimensional 
floating-point array (CITYO); a 5-row by 10-column two-dimensional 
floating point array (STATEO); a 20-row by 10-column two-dimensional 
alpha array (C0DE$()) with each element 5 bytes long; and a 
1000-element one-dimensional integer array (ZIPS). The last two 
arrays are designated as common, as is the integer scalar COUNTS. 

Using DIM and COM statements to specify the length of alpha scalars is 
discussed in Section 3.4.2. 


3-16 Data Formats 



If an array is not dimensioned before its first occurrence in an 
executable program statement, the compiler automatically assigns 
default dimensions of 10 rows by 10 columns, unless the compiler 
option MINANS = YES is selected. In this case, the number of 
dimensions is taken from the first use of the array. In the case of 
alpha arrays, each element is assigned a default length of 16 bytes 
when the compiler option MINANS = NO and 18 bytes when MINANS = YES. 
Therefore, any array that is to be of any other dimension must be 
dimensioned before its first occurrence in an executable statement. 

No array can be dimensioned more than once in a program. Rov/ and 
column dimensions specified in DIM or COM statements must be betv/een 1 
and 32,767. 

The total size of all the variables in a program, including array 
variables, cannot exceed the available segment 2 address space. The 
segment 2 address space is limited to a maximum of 512K (524,288) 
bytes on all VS systems. If the variables in a source program require 
more than 512K bytes of storage, the compiler issues an error message 
and halts code generation. 

Although programs can be compiled with up to 512K bytes of variable 
storage space (segment 2 space), the resulting object program cannot 
be executed unless there is sufficient space available on the 
particular VS configuration at run time. In addition, each user ID 
has an associated maximum segment 2 size that can be less than or 
equal to the system maximum; a program will not run unless a user's 
segment 2 size is sufficiently large. 

Thus, the fact that a particular program compiled successfully on a 
particular system does not guarantee that it will also run on that 
system. For example, on a VS system with only 256K bytes of Segment 2 
space allocated to each task, a program requiring 400K of Segment 2 
space will compile with no errors (assuming it were syntactically 
correct), but will not rxan because of insufficient memory to store the 
variables during execution. Likewise, a user with a segment 2 size of 
256K bytes on a system with a maximum of 512K bytes can compile a 
program requiring 400K bytes of variable storage, but the compiled 
program will not run. 

Since DIM statements are processed during compilation, prior to 
program execution, they cannot be supplied with variable subscripts, 
since the value of the variable is unknown at that time. The 
following statement, for example, produces an error message: 

DIM A1(5,N) 
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CHAPTER 4 
NUMERIC OPERATIONS 


4.1 INTRODUCTION 

Numeric data (refer to Section 3.3) is manipulated in VS BASIC by 
means of operators and functions. An operator is a symbol (such as + 
or -) that specifies some operation (such as addition or subtraction) 
to be performed, usually involving two numeric quantities. 

Section 4.2 discusses operators. 

A function is a construct that performs some series of operations. 
These operations may or may not be performed on one or more input 
values (called arguments ) to return a single output value. For 
example, SIN(X) and SQR(X) are functions that calculate the sine and 
square root of an argument, in this case of the variable X. 

Section 4.4 discusses functions. 

A number of numeric constants, variables, and functions connected by 
numeric operators constitutes a numeric expression . When values are 
supplied for any variables in an expression, the value of the 
expression is determined by performing the indicated operations and 
functions. This occurs when a statement containing an expression is 
executed when a program is run. The value of the expression is then 
used in whatever way is indicated by the particular statement being 
processed. Section 4.3 discusses expressions. 


4.2 NUMERIC OPERATORS 


There are three types of numeric operators used in BASIC: assignment, 
arithmetic, and relational. The assignment operator assigns a value 
to a particular variable. The arithmetic operators specify the basic 
arithmetic operations that can be performed on numeric quantities; 
addition, subtraction, multiplication, division, exponentiation, and 
negation. Relational operators specify comparisons to be made between 
two numeric values so that a program may take different actions 
depending on whether one value is greater than, equal to, or less than 
another. 
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4.2.1 The Assignment Operator 




The equal sign (=) is the assignment operator used only in assignment 
statements. An assignment statement stores the value of the 
expression on the right of the equal sign in the variable(s) named to 
the left of the equal sign. An assignment statement consists of the 
optional reserved word LET, followed by one or more variable names, 
followed by the equal sign, followed by a numeric expression. For 
example, 

LET SUM = A+B 

LET SQUARE(5,17) = {ZOWK-POW)+10 

LET SLITHEY_TOVES, MOME_RATHS = VORPAL/FRUMIOUS 

You can omit the keyv/ord LET. For example, 

DIFFERENCE = A-B 
CABBAGES, KINGS = 10 

Note that the equal sign has a different meaning in contexts other 
than assignment statements (refer to Section 4.2.3). 


4.2.2 Arithmetic Operators 

The following symbols are used as arithmetic operators: 


Symbol 

Operation 

Sample Expression 

Explanation 

T or ** 

exponentiation 

A t B or A ** B 

Raise A to the powe: 

* 

multiplication 

A * B 

Multiply A by B. 

/ 

division 

A / B 

Divide A by B. 

+ 

addition 

A + B 

Add B to A. 

- 

subtraction 

A-B 

Subtract B from A. 

- 

unary negation 

-A 

Negate A. 




NOTE 


All arithmetic operations must be explicitly specified. In normal 
algebraic notation, you can use expressions such as A£ or A(B) to 
indicate multiplication; in BASIC, you must explicitly specify the 
operation (e.g., A*B). 
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When a numeric expression is evaluated, arithmetic operations are 
performed in the following order or hierarchy: 

1. All operations within parentheses are performed. The innermost 
parenthesized expressions are evaluated first. 

2. Selecting the compiler option MINANS = NO means all unary negation 
(-) and exponentiation (T or **) operations are performed (left to 
right). 

3. Selecting the compiler option MINANS = YES means all 
exponentiation operations (t or **) are performed (left to right). 

4. All multiplication (*) and division {/) operations are performed 
(left to right). 

5. Selecting the compiler option MINANS = NO means all addition (+) 
and subtraction (-) operations are performed (left to right). 

6. Selecting the compiler option MINANS = YES means all addition (+), 
subtraction (-), and unary negation (-) operations are performed 
(left to right). 


NOTE 


You must follow every arithmetic operator with a numeric expression. 
Thus it is not permissible to have an operator immediately followed by 
another operator, as in A B. To indicate an operation on the 
negative of an expression, you must use parentheses to enclose the 
expression and the negating minus sign. For example, A * (-B) is 
permissible, but A *- B is not. 


When there are no parentheses in the expression and the operators are 
at the same level in the hierarchy, the expression is evaluated from 
left to right. Parentheses can be used to group operations and so 
alter the order of evaluation of terms within an expression. 
Quantities within parentheses are evaluated before the parenthesized 
quantity is used in further computations. For example, 

A * B / C A is multiplied by B; the product is then 
divided by C. 

A * (B / C) B is divided by C; the quotient is then 
multiplied by A. 
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X + Y * Z 


Y is multiplied by Z (multiplication precedes 
addition by rule 3); the.product is then 
added to X. I 

I 

I 

(X + Y) * Z Y is added to X; the sumiis then multiplied 
by Z. 

Parentheses can be "nested" to any level. That is, a parenthesized 
expression can contain other parenthesized expressions, as in 
A+(B-((C/D)**2)). In such cases, the expression within the innermost 
set of parentheses is evaluated first, and evaluation proceeds to the 
outermost set of parentheses. For every'left parenthesis there must 
be one matching right parenthesis at some later point in the 
expression. ' 

When in doubt, you can always use parentheses to insure that a complex 
expression is evaluated in the intended way. Redundant parentheses 
have no effect on the order of evaluation of an expression. 


^. 2 .3 Relational Operators 

Relational operators are used in IF...TH^ statements when values are 
to be compared. 

I 

For example, when the statement 
IF G<10 THEN 60 

is executed, if the value of G is less than 10, processing continues 
at program line number 60. Otherwise, execution continues in the 
normal sequence with the statement following the IF statement. 

VS BASIC uses the following relational symbols: 

Symbol Sample Relation Explanation 

= A = B A is equal to B. 

< A < B A is less than B. 

<= A <= B A is less than or equal to B. 

> A > B A is greater than B. 

>= A >= B A is greatsr than or equal to B. 

<> A <> B A is not equal to B. 

These symbols are also used in the POS function and the SEARCH 
statement (refer to Section 5.6 and the SEARCH statement entry in Part 
II). 
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4.3 


NUMERIC EXPRESSIONS 




A nvimeric expression is either one or a series of constants, 
variables, or functions, connected by arithmetic operators. Numeric 
expressions can be evaluated in a variety of different BASIC 
statements. In the following examples, valid numeric expressions are 
boxed: 


PHONE 
INDEX 
PRINT 
FOR I 


2988 


(VARX-OFFSET)/LOG(T T 2) 

SIN(THETA) 


3 + K2 

TO 4 * Y 


D(3 + K) - 1 


Most commonly, expressions are evaluated and their values assigned to 
variables in assignment (LET) statements (refer to Section 4.2.1), or 
they are evaluated and their values printed or displayed in PRINT 
statements. Operations in an expression are performed in sequence 
from highest priority level to lowest (refer to Section 4.2.2). 


4.4 NUMERIC FUNCTIONS 

A numeric function is a construct in the BASIC language that takes one 
or more numeric expressions as input values (called argument), 
performs some series of operations on them, and returns a single 
numeric output value. The value of the function can be used anywhere 
a numeric expression is allowed, such as on the right-hand side of an 
assignment statement or as part of a larger numeric expression. 

Syntactically, you write a function in this manner: 

fname[(argument[,argument][,...])] 

where fname is the name of a function, and argument is any expression 
acceptable to the particular function used. Expressions used as the 
arguments of a function are evaluated before the computation indicated 
by the function is performed. You can use the result of this 
computation as part of a larger expression. For example, 

100 LET X = SIN(y / 2) + 1 




causes 

1. the expression Y / 2 to be calculated, 

2. the sine of that expression to be determined (SIN is the function 
name), 

3. 1 to be added to the sine, and 

4. the assignment of the final value to the variable X. 
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vs BASIC recognizes two major kinds of numeric functions: intrinsic 
and user-defined functions. Refer to Sections 4.4.1 and 4.4.2. 


4.4.1 Intrinsic Functions 


Intrinsic (or "built-in") functions are defined within the VS BASIC 
language and can be used at any time in a program. The 25 intrinsic 
functions recognized by VS BASIC include all mathematical functions 
such as trigonometric, absolute value, and logarithmic functions. A 
random number generator and various functions specialized for use in 
data processing are also available. The intrinsic numeric functions 
vary in the type and number of arguments that they require, but all 
return numeric values. 

In addition to the intrinsic functions, VS BASIC also has an intrinsic 
named constant, which is PI. You may use PI anywhere a numeric 
expression is allowed. PI has the value 3.14159265358979. 

The intrinsic numeric functions are presented in the following 
paragraphs and in Part II of this manual. 

The SIZE function, which deals with file I/O, is discussed in 
Section 8.5.4. 


Trigonometric Functions 

The sine, cosine, tangent, arcsine, arccosine, and arctangent 
functions are available in BASIC. Other trigonometric functions can 
be easily expressed using combinations of these functions. Each of 
these functions takes one numeric argument, and returns a floating 
point value. The following table shows the trigonomic functions and 
their meaning: 


Function Meaning 


SIN(x) 

COS(x) 

TAN{x) 

ARCSIN(x) 

ARCCOS(x) 

ARCTAN(x) 

ATN(x) 


The sine of x 

The cosine of x 

The tangent of x 

The inverse sine (Arcsine) of x 

The inverse cosine (Arccosine) of x 

The inverse tangent (Arctangent) of x 

Same as ARCTAN (ATN is a synonym for ARCTAN.) 


These functions can express and accept angular measure in degrees, 
radians, or grads (400 grads = 360 degrees). Radian measure is used 
as the default in every program or subroutine, until one of the 
following statements is encountered: 

• SELECT DEGREES Selects degrees 

• SELECT GRADS Selects grads 

• SELECT RADIANS Selects radians 
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The mode used at any time is determined by the most recently executed 
SELECT statement in that program or subroutine. For instance, a 
program can execute a SELECT DEGREE statement, thus changing the trig 
mode to degrees. If it then uses the CALL statement to call a 
subroutine, the mode becomes radians, assuming the subroutine has not 
previously reset the mode. If the subroutine executes a SELECT GRADS 
statement, the mode for subsequent trigonometric functions becomes 
grads. When the END statement is executed, returning control to the 
calling program, the mode reverts to degrees. If that subroutine is 
called again, the initial mode will be grads. 

The SELECT statement is discussed further in Part II. The arguments 
of the sine, cosine, and tangent functions are interpreted as degrees, 
grads, or radians depending on the SELECT setting in effect at the 
time of execution. The values returned by the inverse trigonometric 
(arc) functions are also shown in degrees, grads, or radians according 
to the SELECT setting. 


Other Numeric Functions 

This section describes the remaining eighteen numeric functions. For 
more detailed descriptions of these functions (including which 
functions return integer values and which return floating-point 
values), refer to the appropriate entries in Part II. 


Function 

Meaning 

Number and 

Type of Arguments 

ABS(x> 

The absolute value 
of the argument: 

-X if X < 0; X if 

X >= 0. 

1 numeric. 

DIM(x{),d) 

The maximxam first or 
second subscript of 
the array x. 

1 array designator (x()), 

1 integer (d) = 1 or 2. 

EXP(x) 

The exponential 
function; "e" 

(2.718...) raised 
to the xth power. 

1 numeric. A float 
binary argument must range 
from -180.217823392959 to 
174.667963000575. A float 
decimal argument must 
range from 

-180.217823392959 to 
145.062860858624; 0 is 
returned for values less 
than -149.668031044613. 
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Function 

Meaning 

Number and 

Type of Arguments 

INT{x) 

The greatest integer 
less than or equal 
to X. 

1 numeric. The input 
value cannot be 
outside the range of 
legal integers. 

LEN(a$) 

The actual length, 
in bytes, of a$. 

1 alphanumeric. 

LGT{x) 

Common (base 10) 
logarithm of x. 

1 numeric. 

LOG(x) 

Natural (base "e”) 
logarithm of x; 
inverse function 
of EXP. 

1 numeric. 

MAX{x,y,z,...) 

The value of the 
largest element in 
the argument list. 

1 or more numeric scalars 
or numeric array 
designators. 

MIN{x,y,z,...) 

The value of the 
smallest element in 
the argument list. 

1 or more numeric scalars 
or numeric array 
designators. 

MOD{x,y) 

The modulus function; 
the remainder of the 
division of x by y. 

2 numeric. 

NUM{a$) 

The number of sequen¬ 
tial ASCII characters 
in a$, starting with 
the first character, 
that represent a legal 
VS BASIC number. 

1 alphanumeric. 

POS(a$<b$) 

The position of the 
first character of 
a$ that is <, < =, 
>,>=,< >, or = 
the first character 
of b$. 

2 alphanumeric. 

RND(x) 

A pseudorandom number 
between zero and one. 

1 numeric. 
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Function 

Meaning 

Number and 

Type of Arguments 

ROUND(x,n) 

The value of x, 
rounded off to n 
decimal places. 

1 numeric (x), 1 
integer (n). 

SGN(x) 

The signum function; 

-1 if X is negative, 

0 if X is zero, or +1 
if X is positive. 

1 numeric. 

SIZE(#n) 

The size, in bytes, of 
the most recently read 
record from file #n. 
(See Section 8.5.4.) 

1 integer file-expression. 

SQR(x) 

The square root of x. 

1 numeric. 

VAL(a$,d) 

The numeric value of 
the first d bytes 
of a$. 

1 alphanumeric (a$), 

1 integer (d) = 1,2,3, 
or 4. 


The following three sections discuss the DIM, RND, and ROUND functions 
in more detail. 

DIM 

The DIM function (not to be confused with the DIM statement) requires 
two arguments: the first must be an array-designator (the array name 
plus parentheses, e.g., A()) occurring in the BASIC program. The 
second argument must be an expression whose value is either 1 or 2. 

The DIM function returns either the row or column dimension of the 
named array. 

DIM(X(),1) Returns the row dimension of the array X. 

DIM(X(),2) Returns the column dimension of the array X. 

RND 


The RND (random number) function is used to produce a pseudorandom 
number between 0 and 1. The term pseudorandom is used because a 
digital computer cannot produce truly random numbers. Instead, each 
time the RND function is called, it uses an internally-stored number 
as a "seed" from which to generate the next "random" number by a fixed 
internal algorithm. 
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Since the algorithm is always the same, it produces the same value for 
a given seed value every time. By calling the RND function repeatedly 
and using the output value of each call as the seed for the next one, 
a sequence of numbers is generated that, though obviously not truly 
random, is scattered about in the range zero to one in such a manner 
as to appear random; thus the term pseudorandom. 

When the compiler option MINANS = YES is selected, the RND function 
requires no argument to generate the next pseudorandom number between 
zero and one. When this function is used with the RANDOMIZE 
statement, unpredictable sequences of pseudorandom numbers are 
generated. When the RANDOMIZE statement is not used, each sequence of 
execution of the RND function in each program's invocation generates 
the same sequence of pseudorandom numbers. 

When the compiler option MINANS = NO is selected, there are three 
different ways in which the RND function can be used: (1) to generate 
a pseudorandom number based on a seed value; (2) to reset the seed 
value to some number specified by your program (as either a constant 
or a variable); (3) to reset the seed value based upon the time-of-day 
clock when the program is run. The mode of operation selected depends 
upon the value of the expression used as an argument in the function 
RND{expn) as described in the following options: 

1. expl < 0 or expl >= 1 

If the argument (expl) is less than zero or greater than or equal to 
one, RND produces a pseudorandom number from the seed value. If this 
is the first use of RND in the program, the seed has a value set by 
the VS BASIC compiler during compilation. Otherwise, it has the 
value produced by the last RND call executed. 

2. 0 < exp2 < 1 

If the argument (exp2) is between zero and one, RND returns the 
argument itself as the result and resets the seed to this value. The 
next use of RND, as in option 1 above, uses the value of the previous 
argument (exp2) as the seed from which to generate a pseudorandom 
value. This allows you to produce the same sequence of random 
numbers any number of times within the same program or within 
different programs. 

3. exp3 = 0 

If the argument is equal to zero, RND produces a number whose value 
is computed from the time of day when the RND function is executed, 
rather than from a user or compiler specified value. You can use 
this option to reset the seed to a random value, so that on 
subsequent calls using option 1, a more seemingly random series of 
numbers is produced. 
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Note that although option 3 produces a random number in the sense that 
it generally differs each time this option is used, repeated RND calls 
using this option within a program do not produce a dependably random 
list of numbers. <This is because the relation between successive 
numbers in such a list is a function of the time elapsed between 
function calls.) To produce a more random list, use option 3 once, 
followed by as many Option 1 calls as desired. Use option 3 only to 
reset the random number list to a new starting value, not to produce 
such a list. For example, 

100 LET A = RND{.5) 

200 LET B = RND{2) 

300 LET C = RND{2) 

400 PRINT "A =";A, "B =";B, ”C =”;C 

results in: 

A =.5 B =.259780899273209 C =.2989807370711264 
This program produces the same list of numbers every time it is run. 


ROUND 

R0UND(X,N) is equivalent to the expression: 

SGN(X)*( INT(ABS<X)*10T(INT(N)>+0.5)/10r(INT(N)) ) 


Use the ROUND function to round off the value of X to the precision 
specified by N. If N is positive, X is rounded off so that the last 
significant digit of the function value is the Nth digit to the right 
of the decimal point. If N is negative, X is rounded off so that the 
last significant digit of the function value is the (1 - N)th digit to 
the left of the decimal point. For example. 


R0UND(123.4567,4) = 
R0UND(123.4567,3) = 
R0UND(123.4567,2) = 
R0UND(123.4567,1) = 
R0UND(123.4567,0) = 
ROUND(123.4567,-1)= 
ROUND(123.4567,-2)= 
ROUND(123.4567,-3)= 


123.4567 

123.4570 

123.4600 

123.5000 

123.0000 

120.0000 

100.0000 

0 
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4.4.2 User-Defined Functions 


User-defined functions enable you to specify any sequence of numeric 
operations to be performed on a (optional) single numeric argument and 
to identify that sequence of operations by a function name. Functions 
are defined using the DEF statement. The DEF statement has the form 

DEF fname[%] arg = expr 

where fname is the function name, arg is a "dummy argument," and expr 
is any valid numeric expression. Function names are formed according 
to the same rules that apply for naming scalar variables (refer to 
Subsection 3.3.3). Although you can have functions with the same 
names as variables in a program, it is not recommended. The dummy 
argument "arg" (optional only if MINAWS is set to YES) is used simply 
to indicate the position in the function definition that is to be 
taken by the argument value when the function is called, and it can be 
any valid variable name. For example, 

DEF AREA(X) = 3.14159265 * X ** 2 

defines a function that determines the area of a circle given the 
radius. In this case, AREA is the function name, and X is a dummy 
argument. The function can be called by a statement elsewhere in the 
same program, such as 

LET SEMICIRC = AREA(RADIUS) / 2 

When this statement is executed, the expression in the DEF statement 
is evaluated, with the value of RADIUS substituted for X. This value 
is returned to the LET statement, and is then divided by 2. The 
resulting value is assigned to the variable SEMICIRC. 


NOTE 


A function can be defined anywhere in a program, but if the first use 
of a function precedes its definition, the function name must begin 
with the characters FN. Otherwise, the BASIC compiler interprets the 
function call as an array name reference. This results in either an 
error message at compilation time or in logic errors in the program. 
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4.5 


MIXED-MODE ARITHMETIC 




BASIC allows mixed-mode arithmetic, i.e., floating-point or integer 
variables can be assigned either floating-point or integer values, 
with floating-point values truncated to integers. Specifically, 

1. Assignment ([LET]) statements allow mixed-mode assignment. 

2. Statements performing implicit assignment, such as CONVERT, 
GOSUB'(), INPUT, ACCEPT, READ, and calls to user-defined functions 
allow mixed-mode assignment. The only exceptions to this are the 
CALL and SUB statements, which do not allow mixed-mode argument 
passing. 

3. The percent sign (%), used to indicate an integer value, may only 
be used as a numeric symbol when it appears as such in the source 
file; in particular, INPUT, ACCEPT, GET, READ, and CONVERT do not 
allow % as numeric input. Thus, you must use floating-point 
constants. 

4. Expressions in integer syntax are also treated like mixed-mode 
assignments (truncated to integer), e.g., BIN(expr), END expr, ON 
expr GOTO..., RESTORE expr. 




4.6 SUMMARY OF NUMERIC DATA TYPES AND TERMS 




4.6.1 Floating-Point Data 

The allowable range of magnitudes for float binary values is from 
approximately 5.4 x 10'^® to 7.2 x 10^®; the magnitude of float 
decimal values can range from 1 x 10'®® to approximately 1 x 10®^. 
Floating-point values with magnitudes outside of the operant range 
cause conditions called underflow (magnitude too small) and overflow 
(magnitude too large). 

The following are classified as floating-point values: 

1. The value of any floating-point variable (no % or $). 

Examples: A, OPHIDIAN, FRUIT(3), D4(X,5) 

2. Any numeric constant with no %. 

Examples: 5, 3.7, -6.321E3, lE-1 

3. The result of any valid nuuneric function except LEN, NUM, POS, 
VAL, S(^, SIZE, DIM, ABS(integer), user-defined integer functions 
(the function name ends in %), and under certain conditions MIN, 
MAX, and MOD. 

Examples: FN2(2%), SIN(3), ABS(-12) 
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4. The result of any binary operation (+, f, **) or MOD 

function whose two arguments are not both integers . 

Examples: 2/5, 3%fl7, 4%+SQR(16) 

5. The result of the MAK and MIN functions when the arguments are not 
all integers. 


NOTE 


If the evaluation of any numeric expression during program execution 
results in a float binary value with a magnitude greater than 
approximately 7.2 x 10^® or a float decimal value greater than 1 x 
10®^ (i.e., an overflow condition), an error occurs, program 
execution halts, and an appropriate error message appears on the 
v/orkstation. Evaluation of float binary expressions with magnitudes 
less than 5.4 x 10“^® (underflow) or float decimal expressions with 
magnitudes less than 1 x 10~^^ are treated as zero and do not cause 
an error. A numeric constant that is either too large or too small 
causes an error during compilation. 


NOTE 


When the compiler option MINANS = YES is selected, all floating-point 
processing uses float decimal. In the evaluation of expressions, 
floating-point overflow, division by zero, and zero to a negative 
power in involution generate a warning with execution continuing with 
machine infinity. 


4.6.2 Integer Data 

The allowable range of values for integer values is from 
-2,147,483,648 to 2,147,483,647. 

The following examples are classified as integer values: 

1. The value of any integer variable (variable name ending with %). 
Examples: A%, OPHIDIAN^, FRUm(3), D4%{X,5) 

2. Any integer constant, which must contain a trailing percent sign 
(%), no decimal point, and no exponent. 

Examples: 375%, -10000%, 2% 
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3. The result of the numeric functions LEN, NUM, POS, VAL, SGN, SIZE, 
DIM, ABS (integer), and user-defined integer functions (function 
names ending in ^). 

Examples: FN3%(7.5), SGN(THE_TIMES), SIZE(#5) 

4. The result of any binary operation (+, -, *, /, t, **) or MOD 
function whose two arguments are both integers. 

Examples: 2%/5%, 3%T(17^), 4% + LEN(B$) 

5. The result of the MAX and MIN functions when the arguments are all 
integers. 


NOTE 


If the evaluation of any numeric expression during program execution 
results in an integer value outside the allowable range 
(-2,147,483,648 to 2,147,483,647), an error occurs, program execution 
halts, and an appropriate message is displayed on the workstation. 




4.6.3 


Numeric Terms 


1. Constant: 


2. Expression ^ 
or exp 



floating-point constant 
integer constant 


} 


numeric variable 
constant 

mathematicl function 
DIM function 
LEN function 
NUM function 
POS function 
SIZE function 
user-DEPined function 
VAL function 

< 




> 


V 



(expression) 






‘ Adjacent operators are not allowed (e.g., A ++ B). 


Numeric Operations 4-15 



3. Integer (or int ): digit [digit]...^ 


4. Numeric Array-designator : letter 


letter 'j 
digit L 
underscore I 


m 


(not to exceed 64 letters, digits, and/or underscores) 




5. Numeric Array Name ; letter 

(not to exceed 64 letters, digits, and/or underscores) 



^letter 


6. Numeric Array Variable: letter 

) digit 



1 [.exp] 

f 


V underscore. 



(not to exceed 64 letters, digits, and/or underscores) 




fletter 1 

11 

7. Numeric Scalar Variable; letter 


digit 

^underscore! 

!| 


'letter 'j 
digit V 
underscore J 


[%] 


(not to exceed 64 letters, digits, and/or underscores) 




8. Numeric Variable: 


{ numeric scalar variable) 
numeric array variable j 


9, Mathematical Function : PI, ABS, ARCCOS, ARCSIN, ARCTAN, ATN, COS, 
EXP, INT, LGT, LOG, MAX, MIN, MOD, RND, ROUND, SGN, SIN, SQR, TAN 
f met ions. 
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CHAPTER 5 

ALPHANUMERIC OPERATIONS 


5.1 INTRODUCTION 

Alphanumeric data (or simply alpha data) is manipulated in VS BASIC by 
alphanumeric operators and functions. Alpha operators and functions 
are different from their numeric counterparts described in Chapter 4, 
even though in some cases (such as assignment statements) the same 
symbol may be used as either a numeric or an alphanumeric operator. 

In these cases, the meaning of the symbol is inferred from the data 
type of the two operands involved. Functions that return alpha values 
are called alpha functions. In addition, there are some numeric 
functions that take alpha arguments. Both are discussed in this 
chapter. A series of literals, alpha variables, or alpha fianctions 
connected by alpha operators constitutes an alpha expression . 

In addition to facilities for manipulating characters and strings of 
characters, VS BASIC also provides logical functions that enable you 
to specify operations on individual bits within a stored character. 

It is also possible to convert alphanumeric representations of numbers 
to numeric form and vice versa using the CONVERT statement (refer to 
Part II). 


5.2 ALPHANUMERIC OPERATORS 

The alphanumeric operators in VS BASIC are the assignment operator, 
the concatenation operator, and relational operators. Sections 5.2.1, 
5.2.2, and 5.2.3 discuss these operators. 

5.2.1 The Assignment Operator 

The equal sign (=) is used as the alphanumeric assignment operator in 
a LET statement, just as it is for numeric assignment. An 
alphanumeric assignment statement consists of the reserved word LET 
(optional), followed by one or more alphanumeric variable names or 
other alpha receivers (refer to Section 5.4.2) followed by the equal 
sign, followed by an alpha expression. 
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When the statement is executed, the value of the alpha expression is 
stored into the variable(s) or receiver(s) one character at a time, 
left to right. This continues until all the characters of the 
evaluated expression are used up or until the alpha variable or 
receiver is full. Thus, if the defined length of the alpha receiver 
is less than the length of the evaluated expression, the rightmost 
characters of the value of the expression are lost. 

If the defined length of the alpha variable or receiver is greater 
than the length of the value of the alpha expression, the remaining 
bytes of the alpha expression are filled with trailing blanks when the 
compiler option MINANS = NO is selected, and trailing nulls when the 
selection is MINANS = YES. In addition, string overflow generates a 
fatal error when the selection is MINANS = YES. For example, 

100 DIM A$50, B$5, C$10, D$10 

200 A$ = "THE TIME HAS COME, THE WALRUS SAID" 

300 B$ = A$ 

400 C$ = B$ 

500 D$ = A$ 

600 PRINT A$ : PRINT B$ : PRINT C$ : PRINT D$ 

✓ 

results in; 

THE TIME HAS COME, THE WALRUS SAID 
THE T 
THE T 

THE TIME H 

5.2.2 The Concatenation Operator 


The concatenation operator {&> combines two strings, one directly 
after the other, without intervening characters. The two strings 
combined by the concatenation operator are treated as a single 
string. For example, 

100 A$ = "WASTE" 

200 B$ = "LAND." 

300 C$ = A$ & B$ 

400 PRINT C$ 

results in: 

WASTELAND. 

Literal strings expressed as constants can be concatenated with 
literal strings stored as the values of alpha variables. For example, 

100 A$ = "BY" 

200 B$ = "T.S. ELIOT" 

300 C$ = A$ 5c " " & B$ 

400 PRINT C$ 
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results in: 


BY T.S. ELIOT 

Any legal alpha expression, including HEX literal strings, can be 
concatenated with alpha literals or alpha variables. For example, 

100 A$ = "APRIL IS THE CRUELEST MONTH" 

200 C$ = A$ & HEX<2C) & " BREEDING" /* HEX(2C) = "," */ 

300 PRINT C$ 

results in: 

APRIL IS THE CRUELEST MONTH, BREEDING 


5.2.3 Relational Operators 

Relational operators are used in IF...THEN statements and in the POS 
function (refer to Section 5.6.3) to compare values of alphanumeric 
data. 

In IF...THEN statements, the values of two strings are compared one 
character at a time on the basis of their position in the ASCII 
collating sequence (refer to Appendix G). In such a comparison, the 
first characters of each string are compared. If they are different, 
the string containing the character of a higher position in the 
collating sequence is the greater of the two. If they are the same, 
the second characters of the two strings are compared in the same way. 

When the compiler option MINANS = NO is selected, this process is 
repeated until a pair of unequal characters is found or until one or 
both strings is exhausted. If the strings are of unequal length, the 
shorter one is treated as though it had enough trailing blanks to make 
it the same length as the longer one, and the comparison continues one 
character at a time. This usually places the shorter string earlier 
in the collating sequence, since few characters have a lower ASCII 
value than the space (HEX(20)). If the strings are of equal length 
and the comparison shows all characters to be the same, the strings 
are equal. 

When the compiler option MINANS = YES is selected, strings are equal 
only if their significant characters are equal and they are of equal 
effective length. Trailing blanks are considered significant. 

The relational operators used with alphanumeric data are the same as 
those used for numeric relations. They have the following meanings 
when used with alphanumeric data: 
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Symbol 

Sample Relation 

Explanation 


A$ = B$ 

A$ is at the same position as B$ in the 
collating sequence. 

< 

A$ < B$ 

A$ precedes B$ in the collating 
sequence. 

<= 

A$ <= B$ 

A$ precedes or is at the same position 
as B$ in the collating sequence. 

> 

A$ > B$ 

A$ follows B$ in the collating sequence 

>= 

A$ >= B$ 

A$ follows or is at the same position 
as B$ in the collating sequence. 

<> 

A$ <> B$ 

A$ is at a different position from B$ 
in the collating sequence. 

ALPHA 

ARRAY STRINGS 



You can treat an entire alpha array as a single alpha variable 
wherever an alpha variable would be allowed. In this case, refer to 
the alpha array by its name followed by (), the same form used for 
array-designators. The array is treated as a single continuous 
character string, called an alpha array string, which in memory is 
equivalent to a row-by-row path through the elements of the array. 
For example, 

100 DIM A$(2,2)3 

200 A$(l,l) = ••1":A$<1,2) = "2’':A$<2,1) = "3":A$(2,2) = ”4'' 

300 PRINT A$() 

results in: 

12 3 4 

Although alpha array strings and alpha array-designators look alike, 
their usage is generally determined by the syntax. There are cases, 
however, in which both scalars and arrays are allowed. In these 
cases, an argument such as A$() is always regarded as an 
array-designator, never as an array string. The statements in which 
this can occur are: 

ACCEPT CALL GET DISPLAY SUB PUT Disk I/O Statements 

In these cases, you can use STR (e.g., STR (A$(})) to indicate that 
the variable is to be treated as an array string and not as an array 
designator. 
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5.4 


ALPHA EXPRESSIONS AND ALPHA RECEIVERS 


5.4.1 Alpha Expressions 

An alpha expression is either one or a series of literals, alpha 
variables, alpha array strings, or alpha functions connected by 
concatenation operators (&). Alpha expressions can be evaluated in a 
variety of VS BASIC statements. In the following example, valid alpha 
expressions are boxed: 


A$ = I B$ 


IDENT$ = I NAME$ & & ADDRESS$ & & SOCSEC$ 


PRINT I TEMP$(I) 


HEX(OB) 


IF I STR(PHRASE$(I)) | >= I KEY(#1) | THEN 

REARRANGE 


FOR K=1 TO LEN( | CUCUMBER$() | ) 


5.4.2 Alpha Receivers 

An alpha receiver is an alphanumeric item into which data can be 
stored, such as a variable or an array. Alpha receivers are used 
wherever a value is "received,'* e.g., on the left side of a LET 
statement, in the argument list of a READ statement, etc. 

The following expressions are the only legal alpha receivers in 
VS BASIC: 

alpha variable (e.g., A$, A$(l,2)) 
alpha array string (e.g., B$()) 

STR function* (e.g., STR(A$,1,1}) 

KEY function (refer to Section 8.5.2) 


* Only when the first argument is an alpha receiver. 
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5.5 ALPHANUMERIC FUNCTIONS 




Eight VS BASIC fimctions return alphanumeric values. The following 
table describes these functions and their meaning. 


Function 

Meaning 

Number and Type 
of Arguments 

ALL(a$) 

A character string consisting 
entirely of characters equal 
to the first character of a$. 

1 alphanumeric 

BIN(x,d) 

An alphanumeric string of 
d characters whose decimal 
ASCII value is the integer 
part of X. 

1 numeric (x), 

1 integer (d) = 1, 2, 

3, or 4 

DATE 

A six-character string 
giving the current 
date in the form YYMMDD. 

None 

FS(#n) 

A two-character code 
indicating the file 
status for the most 
recent I/O operation 
involving file #n. 

(See Section 8.5.) 

1 file expression 

KEy(#n) 

The value of the key 
field for the last 
record read from file 
#n. (See Section 8.5.) 

1 file expression 

MASK(#n) 

The value of the two- 
character alternate key 
mask for the last record 
read from file #n. 

(See Section 8.5.) 

1 file expression 

STR(a$,n,m) 

The substring of a$ 
that begins at the 
nth character of a$ 
and is m characters long. 

1 alphanumeric (a$), 

2 numeric (n,m) 

TIME 

An eight-character 
string giving the time 
of day to the hundredth 
of a second in the form 
HHMMSShh. 

None 
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Further discussion of these functions can be found under their 
respective entries in Part II of this manual. 


NOTE 


You can use the STR function to refer to the entire defined length of 
an alpha variable, including trailing blanks, by omitting the second 
two arguments. Refer to Part II of this manual for examples of this 
use. 


5.6 NUMERIC FUNCTIONS WITH ALPHA ARGUMENTS 


VS BASIC supports four functions that take alpha expressions as 
arguments and return integer values. These are summarized in the 
following table, and are described in more detail in Sections 5.6.1 
through 5.6.4. 


Function Name 

Sample Expression 

Meaning 

LEN 

LEN(X$) 

The current length of the 
argument. 

NUM 

NUM(X$) 

The number of consecutive 
characters in the argument, 
starting at the first, that 
form an ASCII representation 
of a valid VS BASIC number. 

POS 

POS(X$="$”) 

The position within the first 
argument of the first 
character that satisfies the 
indicated relation (equal to, 
less than, greater than) with 
the second argument. 

VAL 

VAL(X$,N) 

The decimal equivalent of 
the binary numeric value of 
the first N characters 
of X$. 


5.6.1 LEN 


The LEN function requires an alpha expression as its argument. LEN 
returns an integer value that is the actual length of the arg\iment. 
The length of a string of all blanks is one. For example, 

LEN("ABCDE") Returns 5. 

LEN(E$) Returns the actual length of E$. 

LEN(STR(E$)) Returns the defined length of E$. 
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Note that the following relation is always true: 
LEN{A$&B$) = LEN(A$)+LEN(B$) 

5.6.2 NUM 


The NUM function requires an alpha expression as an argument, and 
returns an integer value equal to the number of sequential characters 
in the argument that form a legal VS BASIC floating-point constant. 
Allowable characters are 0 through 9, E, period (.), plus sign (+), 
minus sign {-), and space (in the leading or trailing position), 
provided that they conform to the syntax for floating-point constants. 

The count begins with the first character of the argument, and ends 
with the first character that violates the floating-point syntax. NUM 
searches the entire defined length of the argument. If no characters 
are found that violate the floating-point syntax, NUM returns the 
defined length. If the argument is entirely blank, NUM returns 0. 
Leading and trailing spaces are included in the count. Thus: 

NUM ("IE 88") returns 1 
NUM {"1E8 8") returns 4 
NUM {" 1E8 8") returns 5 

You can use NUM to validate an alphanumeric representation of a number 
before attempting to convert it to internal numeric binary form with 
the CONVERT statement, which is described in Part II of this manual. 

NUM does not stop its search after finding more than fifteen digits in 
the numeric constant, even though subsequent attempts to evaluate that 
number ignore all digits other than those belonging to an exponent 
after the fifteenth significant digit. 

Note that NUM does not check the value of a number, only whether it is 
formatted correctly. Thus NUM("1E88") returns 4, even though 1E88 is 
greater than the largest allowed floating-point constant. 
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The POS function requires three components in its argument (not to be 
separated by commas): (1) an alpha expression, optionally preceded by 
a minus sign; (2) a relational operator; and (3) a second alpha 
expression. The relational operator is taken from the following set: 

< 

<= 

> 

>= 

<> 


The POS function searches the first string for a character that 
satisfies the specified relation to the first character of the second 
string. Thus, POS (E$< = "*") searches E$ for a character less than 
or equal to 

Comparisons are based on the ASCII-coded values of the characters. 
Thus, searching a string for a character less than or equal to the 
space character means searching a string for a character whose 
hexadecimal value is less than or equal to HEX (20), the ASCII value 
of the space character. 

The POS function returns an integer value that is the position in the 
first expression where the comparison first succeeds. The leftmost 
position in the expression is named 1; the position to the right of 
that is 2, and so on. If no character is found within the first 
expression that satisfies the relation, POS returns a value of 0. 

The optional minus sign to the left of the first alpha expression 
indicates the direction of the search. Normally, searches are from 
left to right. If the minus sign is present, the search proceeds from 
right to left. The entire defined length of the expression is 
searched imtil either a match is found or the expression is 
exhausted. P0S(E$ = " ") returns the position of the leftmost space 
in E$. P0S(-E$ = " ") returns the position of the rightmost space. 
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When comparing alpha string variables with literal strings or other 
alpha variables (e.g., IF A$ < "ABC”), values are compared character 
by character. Trailing spaces are considered equivalent to HEX(20) in 
determining where to place each value in the collating sequence. The 
values fall at the same location in the collating sequence (i.e., they 
are equal) even if they do not have the same number of trailing 
spaces, as long as all their other characters are equal. For example, 

100 DIM A$4, B$5, C$5 
200 A$ = "ABC" 

300 B$ = HEX(41424321) /* HEX(41424321) = "ABC!" */ 

400 C$ = "ABC " 

500 IF A$ = B$ THEN 800 
600 IF A$ = C$ THEN 1000 

700 PRINT "A$ NOT EQUAL TO B$ OR C$." : GOTO 1100 
800 PRINT "A$ = B$: ";A$;" = ";B$ 

900 GOTO 1100 

1000 PRINT "A$ = C$; ";A$;" = ";C$ 

1100 END 

results in: 


A$=C$: ABC=ABC 


5.6.4 

The VAL function requires an alpha expression as an argument. A digit 
whose value is 1, 2, 3, or 4 can be supplied as a second argument; if 
it is omitted, a value of 1 is assumed for the second argument. 

The VAL function extracts up to four characters from the alpha 
expression, depending on the value of the second argument, and returns 
a decimal integer that is equivalent to the binary value of the 
extracted character(s). 

VAL(A$) or VAL(A$,1) simply returns the decimal value of the ASCII 
code for the first character of A$. For instance, VAL("A",1) is 65, 
VAL("B",1) is 66, and so on. The value ranges from 0 through 255. 

The value returned is the decimal equivalent of the character's binary 
ASCII code, not the hexadecimal value. 

VAL{A$,2) returns an integer whose value is: 

(code for first character) * 256 + (code for second character) 

It is in the range 0 through 65,535. 

VAL(A$,3) returns a value between 0 and 16,777,215: 

(code for first character) * 65,536 + (code for second character) * 
256 + (code for third character) 
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VAL(A$,4) computes the following value: 

(code for first character) * 16,777,216 + (code for second character) 
* 65,536 + (code for third character) * 256 + (code for fourth 
character) 

This computation requires all 32 bits of the integer; in addition, 
overflow can occur, causing the result to be a negative integer. The 
value of the result ranges between -2,147,483,648 and 2,147,483,647, 
inclusive. 

You can use the BIN fxinction to extract characters from an integer 
expression containing their binary values, reversing the operation 
performed by VAL. 


5.7 LOGICAL EXPRESSIONS 

The alpha operators and functions discussed so far have all involved 
manipulating single characters and strings of characters. It is also 
possible to manipulate individual bits within the bytes that represent 
stored characters. This is done in a special type of alpha 
expression, called a logical expression , that can be used only on the 
right-hand side of an assignment (LET) statement. 

Logical expressions are alpha expressions that contain any of several 
logical operators and have the general form: 

[operator] operand [operator operand] ... 

where operator is one of: 

ADD[C] 

AND 

OR 

XOR 

BOOLh 

and where operand is an alpha expression or ALL(alpha expression). 

Note that concatenation (&) and parentheses are not allowed within 
logical expressions. 


5.7.1 Evaluating Logical Expressions 

A statement of the form "LET alpha receiver = logical expression" is 
evaluated as follows: 

1. If the expression begins with an operand, the receiver is assigned 
that operand (i.e., as in a simple LET statement). 
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2. From left to right, the next operator operates on the operand to 
its right and the receiver (i.e., the receiver is used as an 
operand). In all cases, the defined lengths of both arguments are 
used, with the operation proceeding one byte at a time as follows: 

a. AND, OR, XOR, BOOLh — The operation proceeds one byte at a 
time from left to right . If the operand is shorter than the 
receiver, the remaining characters of the receiver are 
unchanged. If the operand is longer than the receiver, the 
operation stops when the receiver is exhausted. The specific 
effects of these operators are described in Section 5.7.2. 

b. ADD, ADDC — The operation proceeds one byte at a time from 
right to left . If the operand and receiver are not the same 
length, the shorter one is left-padded with hex zeros. The 
result is right-justified in the receiver, with high-order 
characters truncated if the result is longer than the 
receiver. The specific effects of these operators are 
described in Section 5.7.2. 

3. The receiver always gets the result of the operation; step 2 is 
then repeated until all operator-operand pairs are used up. 

Part of an alpha variable can be operated on by using the STR function 
to specify a portion of the variable. For example, 

100 STR(A$, 3, 2) = ADD B$ 
operates only on the third and fourth bytes of A$. 


5.7.2 Logical Operators 

In the following examples, assume A$ has a defined length of two bytes. 

AND Logically ANDs the two operands, one byte at a time, 
as indicated in Table 5-1. For example, 

LET A$ = HEX(OFOF) AND HEX(OFFO) 

results in: A$ = HEX(OFOO) 

OR Logically ORs the two operands, one byte at a time, 
as indicated in Table 5-1. For example, 

LET A$ = HEX(OFOF) OR HEX(OFFO) 

results in: A$ = HEX{0FFF) 
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XOR Logically exclusive-ORs the two operands, one byte at 
a time, as indicated in Table 5-1. For example, 

LET A$ = HEX (OFOF) XOR HEX (OFFO) 

results in: A$ = HEX(OOFF) 

BOOLh Performs one of 16 logical operations specified by 
the value of the hexadecimal digit h. Refer to the 
entry in Part IT under BOOLh for a description and 
examples of these operations. 

ADD Adds the binary values of the operands, one byte at a 
time, with no carry propagation between bytes. For 
example, 

LET A$ = HEX(0123) ADD HEX(OOFF) 
results in: A$ = HEX(0122) 

ADDC Adds the binary values of the operands, one byte at a 
time, with carry propagation between bytes (like two 
long binary numbers). For example: 

LET A$ = HEX(0123) ADDC HEX(OOFF) 

results in: A$ = HEX(0222) 


Table 5-1. Logical Operations 


Logical Operator 

Operand 1 
Bit = 

operand 2 
Bit = 

Result 

Bit = 

AND (Result = 1 if both 

0 

0 

0 

operand bits = 1. 

0 

1 

0 

Otherwise, 

1 

0 

0 

result = 0.) 

1 

1 

1 

OR (Result = 1 if either 

0 

0 

0 

or both operand bits 

0 

1 

1 

= 1. Otherwise, 

1 

0 

1 

result = 0.) 

1 

1 

1 

XOR (Result = 1 if one 

0 

0 

0 

or the other but 

0 

1 

1 

not both operand 

1 

0 

1 

bits = 1. Otherwise, 
result = 0.) 

1 

1 

0 
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5.8 


SUMMARY OF ALPHANUMERIC DATA FORMATS AND TERMS 


5.8.1 Alphanumeric Length 

1. Actual or Current Length (in bytes) 

(as determined by LEN function) 

a. Alpha Variable — When the compiler option MINANS = NO is 
selected/ trailing blanks are not included and if all blank/ 
the length equals 1. When the compiler option MINANS = YES is 
selected/ and if all nulls/ the length equals 0. 

b. Alpha Array String — Like a single long alpha variable . 

c. Alpha-expression — Length equals the sum of the actual lengths 
of the concatenated arguments. 

d. STR function — Length is the number of characters extracted, 
including trailing blanks. 

e. KEY function — Length is the key length specified in SELECT. 

f. Literal — Length is the number of characters within quotes or 
the number of hexadecimal digit pairs in HEX. 

g. FS function — Length = 2. 

h. DATE function — Length = 6. 

i. TIME function — Length = 8. 

j. MASK function — Length = 2. 

k. BIN function — Length as specified by the second argument of 
BIN (1/ 2/ 3/ or 4; default = 1). 

2. Defined Length 

a. Alpha Variable — As specified in DIM, COM, or most recent MAT 
REDIM. (Default = 16 when the compiler option MINANS = NO is 
selected and 18 when MINANS = YES.) 

b. Alpha Array String — Product of three dimensions (e.g., row, 
column, element length) in DIM, COM, or most recent MAT REDIM. 
(Default 10 x 10 x 16.) 

c. Alpha-expression — Except alpha variables and alpha array 
strings. These are the same as the actual length. 

d. All Other Alpha Forms — Same as the actual length. 
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5.8.2 Alphanumeric Terms 


{ letter 
digit 

underscore 




(not to exceed 64 letters, digits, and underscores) 


{ letter 
digit 

underscore 


... $ 


(not to exceed 64 letters, digits, and underscores) 

{ letter 'j 

digit \ ... $() 

underscore] 

(not to exceed 64 letters, digits, and underscores) 

{ letter ^ 

digit V ...$(exp[,exp]) 

underscore] 

(not to exceed 64 letters, digits, and underscores) 


5. Alpha Variable: 


[alpha scalar variable] 
[alpha array variable I 


{ letter 
digit 

underscore 


... $() 


(not to exceed 64 letters, digits, and underscores) 
(Treated as a single long alpha variable) 


7. Literal : 
(when MINANS=NO) 


any 

character 

except 


any 

character 

except 


any 

character 

except 


any 

character 

except 


(when MINANS = YES) 


HEX(hh[hh]...) 
/any 

I character* 


j ncharacter*!I ... 


*As long as the first character is not a quotation mark ("). 
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8. h: a hex digit (0,1,2,9,A,B,C,D,E, or F) 


9. Alpha Receiver; 


^alpha variable 
I STR(alpha receiver[,[exp][,exp]])! 
S alpha array string 
I^KEY (file expression [,exp]) 


10. Alpha Expression 
(or Alpha-exp ); 


alpha receiver 
literal 
DATE function 
TIME function 
J BIN function 
MASK function 
FS (file expression) 
alpha exp & alpha exp 
(alpha expression) 

^STR (alpha-exp[,[exp][,[exp]]])^ 


11. Logical Expression ; 

[operator] operand [operator operand] 
where; 

rADD[C]\ 

AND 




operator = < BOOLh > 
OR 

V XOR ) 


Operand = Jalpha expression! 

IALL function j 


5.8.3 Alphanumeric Operations 

1. The following applies to alpha values used in any BASIC functions 
or operations: 

a. In statements that can alter the values of variables (e.g., 

LET, COPY), values of alpha expressions that are not acting as 
receivers are copied to a temporary location*; the value in the 
temporary location is then used in whatever operations are 
specified. This includes alpha receivers enclosed in 
parentheses. 

Alpha receivers , on the other hand, are never moved, but are 
operated on in place, except in the TRAN statement (described 
in Part II of this manual). The differences in results that 
can occur depending upon whether an expression is a receiver 
are most apparent in multiple assignment (LET) statements; LET 
statements incorporating ADD, AND, OR, XOR, BOOLh; and COPY 
statements. 


* An expression is said to be "acting as a receiver" in the context of 
a particular statement if it is syntactically a receiver (refer to 
Section 3.2) and is also being assigned a new value in that 
statement. 
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For example, 

100 LET A$ = "A" 

200 LET B$ = "B" 

300 LET A$,B$,C$ = A$ & B$ /*THIS IS A MULTIPLE "LET”*/ 

400 PRINT A$,B$,C$ 

prints: 

AB AB AB 

When statement 300 is executed, the value of A$ ("A") is 
concatenated with the value of B$ ("B") and the result ("AB") 
is stored in a temporary location. This string is then copied 
from the temporary location into A$, B$, and C$ sequentially. 

If a temporary location is not used, statement 300 is 
equivalent to 

300 LET A$ = A$&B$ : LET B$ = A$&B$ : LET C$ = A$&B$ 

and the program prints 

AB ABB ABABB 

b. In general, any operation requiring character comparison or 

movement is done one character at a time. This applies to each 
of the functions in the example. 

2. TRAN always moves the translation alpha expression to a separate 
translation table that is inaccessible to you. Therefore, TRAN 
can never translate its own table. 

3. Statements that perform multiple assignments always assign values 
from left to right. This applies particularly to LET, INPUT, 
ACCEPT, GOSUB'O, READ, and GET. This can be an important 
consideration, especially when receivers in the same location are 
specified more than once in the receiver list. 
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OiAPTER 6 

CONTROL STATEMENTS 


6.1 INTRODUCTION 

A VS BASIC program is normally executed in ascending line-number 
sequence, with multiple statements on a line executed from left to 
right. VS BASIC also provides a number of statements, called control 
statements , that can be used to alter the normal sequence of 
execution. Figure 6-1 illustrates these control statements. 


CALL 

FOR...NEXT 

INPUT (some cases) 

RETURN 

IF...THEN...ELSE 

ACCEPT (some cases) 

END 

ON...GO TO 

STOP 

(30SUB 

ON...GOSUB 

Unusual condition and 

GOSUB' 

GOTO 

error/data conver¬ 
sion exit clauses 
for some statements 


Figure 6-1. VS BASIC Control Statements 


Control statements provide VS BASIC with the following facilities: 

1. Halting Execution — END, if encountered in a program, terminates 
program execution and returns control to the Command Processor 
menu or to the invoking program or procedure. If encountered in a 
subroutine, END returns program control to the calling program 
(refer to number 3 in this list). When the compiler option 
MINANS = NO is selected, STOP temporarily halts execution until 
you press the ENTER key or, under defined conditions, one of the 
PF keys. When the compiler option MINANS = YES is selected, STOP 
causes the execution of the program to be suspended. When you 
then press ENTER (or any other PF key), the program is 
terminated. This rule also applies when the STOP statement is in 
a subroutine compiled with the MINANS = YES compiler option. 
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INPUT, ACCEPT, and STOP (when MINANS = NO) temporarily halt 
execution to enable you to supply the program with runtime data, 
or, under defined conditions, to press a PF key. These statements 
are discussed in Chapter 7 and under their separate entries in 
Part II of this manual. 

2. Unconditional Program Branching — GOTO transfers control to the 
line number or statement label specified by the GOTO statement. 

The GOTO statement is discussed under its entry in Part II. 

3. Conditional Branching — IF...THEN...ELSE enables the program to 
test a relationship (the operand of the IF clause) and branch 
according to the result of the test. If the relationship is true, 
the THEN clause is executed and the ELSE clause is not. If the 
relationship is not true, the ELSE clause (or in the absence of an 
ELSE clause, the next sequential executable statement) is executed 
and the THEN clause is not. The IF statement is discussed under 
its entry in Part II. 

4. Branching to Subroutines — GOSUB, GOSUB', and CALL transfer 
control to various kinds of subroutines. After their execution, 
control can be returned to the main body of the program by RETURN 
or END. GOSUB and GOSUB' are discussed under their entries in 
Part II. Section 6.3, Section 6.4, Section 6.5, and Part II 
discuss subroutines. 

5. Looping — A useful feature of BASIC is its ability to execute a 
defined section of code repeatedly. This section of code is 
called a loop. VS BASIC provides a pair of statements, FOR and 
NEXT, that automatically mark a loop and determine the number of 
times it is executed. FOR and NEXT are discussed under their 
entries in Part II. 

6. Unusual Condition Exits — VS BASIC provides a number of exits for 
data error and end-of-data conditions that would otherwise result 
in termination of a program. These include the DATA, lOERR, and 
EOD (end-of-data) clauses in the file I/O and CONVERT statements. 
These clauses in file I/O statements are discussed in Section 8.6, 
and in the appropriate entries in Part II. 


6.2 STATEMENT LABELS 

Any statement in a VS BASIC program can be identified by a statement 
label that immediately precedes it. A statement label (or simply a 
"label") can be any string of up to 64 letters, digits, and 
underscores, provided that the first character is a letter and that 
the string is not a VS BASIC reserved word (refer to Section 2.2 and 
Appendix A). 


6-2 Control Statements 



Using labels, you can write statements that alter the flow of program 
execution without having to keep track of line numbers. For example, 
instead of writing GOTO 100 (where 100 is a program line number), you 
can write C30T0 PART2, where PART2 is a statement label. In this case, 
execution continues with the first executable statement following the 
label PART2. A label can occur alone on a line, or at the beginning, 
middle, or end of a line containing one or more statements. If a 
label is followed by one or more statements on the same line, the 
label and the following statement must be separated by a colon. If a 
label occurs alone on a line or at the end of a line, the colon is 
optional. 

The following examples show some samples of correct and incorrect 
usage of statement labels: 

CORRECT : 

1. 500 PART2 

600 PRINT "ENTER DATA FOR PART 2" 

(Label is PART2.) 

2. 900 FIRST_TIME : RAISIN=RAISIN+1 : RETURN 

(Label is FIRST_TIME.) 

3. 100 LET CAT=(10*X)/PI : FIRST : READ Z 

(Label is FIRST.) 

4. 300 READ NAME$, STREET$, PH0NE$ : HENRY 
350 EXCH$=STR(PHONE$, 5, 3) 

(Label is HENRY.) 

INCORRECT : 

1. 200 NEXT : IF KRISP = 99 THEN 6100 

(NEXT is the verb of an executable statement used to terminate 
a FOR...NEXT loop and is therefore a reserved word. Reserved 
words cannot be used as labels.) 

2. 700 LAST ONE 

800 FOR 1=1 TO 100 : READ FRED(I) : NEXT I 

(LAST ONE: labels cannot contain embedded spaces. The 
compiler interprets this as being a single label (LAST) and 
expects it to be followed by a statement terminator, such as a 
colon or the end of the source program line.) 

3. 400 LET B(J)=SQR(X(J)) : LABEL PRINT B(J) 

(LABEL should be separated from the following statement (PRINT) 
by a colon.) 
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4) 1000 CAT&MOUSE : IP CS > MS THEN 1700 

(CAT&MOUSE contains a character {&) that is not a letter, 
number, or underscore so it is invalid as a label.) 


5) 5200 2ND_TIME : GOSUB 7520 

{2ND_TIME; The first character of any label must be a letter.) 


6.3 SUBROUTINES 


A subroutine is a group of program lines that you can invoke from any 
point in a program to perform a specific task. When execution of a 
subroutine is complete, processing normally returns to the point in 
the program from which the subroutine was invoked. You can use the 
same set of instructions in many different points in a program, with 
control returning <if desired) to the part of the program that called 
the subroutine. 

VS BASIC provides internal and external subroutines. Internal 
subroutines are included as part of the code in the main VS BASIC 
source file. They are invoked by a GOSUB or GOSUB* statement or, 
under certain circumstances, by pressing an appropriate PF key while 
execution is halted by INPUT or STOP. Subroutines invoked by GOSUB* 
or a PF key are marked in the source file by a DEP FN* statement. 
Subroutines invoked by GOSUB need not be marked; GOSUB transfers 
control to a specific line number or statement label. 

External subroutines are written as independent files, beginning with 
a SUB statement. After compilation, they are linked to the main 
program through the LINKER utility (refer to Section 1.4.3, 

Section 6.5.3, and the VS Program Development Tools ). The main 
program invokes external subroutines by means of the CALL statement. 
External subroutines can be linked to any number of calling programs, 
making them a useful way to code routines that can be used by more 
than one program. An external subroutine has to be coded only once. 
If it is later changed, it has to be recompiled only once, and the 
calling programs do not have to be modified. 


6.4 INTERNAL SUBROUTINES 


VS BASIC provides three ways of invoking an internal subroutine: 

GOSUB, (30SUB', and pressing PF keys at execution time. Sections 6.4.1 
through 6.4.3 provide brief summaries of these statements. A full 
discussion of each statement can be found under the appropriate entry 
in Part II of this manual. 
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6.4.1 GOSUB Siabrout ines 


The GOSUB statement branches to a line number or a statement label. 

For example, 

500 GOSUB 2000 900 GOSUB RABBIT 

When executed, statement 500 transfers control to line 2000; statement 
900 transfers control to the statement labeled RABBIT. The beginning 
of the subroutine need not be specially marked. Any valid VS BASIC 
statement can begin a GOSUB subroutine. For example, 

2000 REM THIS SUBROUTINE PRINTS THE CURRENT VALUE OF A 
2100 PRINT "A = A 
2200 RETURN 

When a GOSUB statement is executed, the program stores the location of 
the statement that invoked the subroutine. At the end of the 
subroutine, marked in this case by a RETURN statement, execution 
continues at the statement following the GOSUB statement on line 500. 
If the same subroutine is subsequently invoked from line 1200, 
execution continues then at the statement following the GOSUB 
statement on line 1200. The end of a GOSUB subroutine is marked by a 
RETURN or RETURN CLEAR. RETURN CLEAR causes execution to continue 
with the statement following RETURN CLEAR, instead of returning to the 
statement after the GOSUB. 


6.4.2 GOSUB' Sub routines 

The GOSUB' statement branches to a subroutine that is marked by a DEF 
FN' statement. For example: 

500 GOSUB'112 

This statement causes control to pass to the statement DEF FN'112. 

The range of allowable DEF FN' numbers is 0 to 255. Following 
execution of the marked subroutine, control is returned to the 
statement following the GOSUB* by a RETURN, or to the statement 
following the subroutine by a RETURN CLEAR. 

The most important difference between GOSUB and GOSUB' subroutines is 
that the latter allow the passing of an argument list from the main 
program to the subroutine. This is useful where a subroutine may be 
called from different parts of a program to perform the same series of 
operations on different variables. For example, suppose you want to 
write a subroutine to add some variable to the length of an alpha 
variable. Write the subroutine as: 

5000 DEF FN'IOO (STRING$, COUNTS) 

5100 PIGEONS = LEN(STRING$) + COUNTS 
5200 RETURN 
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The subroutine might be called from elsewhere in the program to 
perform its operation on a string called PHONE$ and an integer called 
BCX)K% by the statement 

400 GOSUB'lOO (PHONE$, BOOK%) 

When line 400 is executed, implicit assignment statements are 
performed that assign the current value of PHOME$ to STRING$ and that 
of BOOK% to COUNTS. By this means, the arguments are "passed" to the 
subroutine. When the subroutine is completed (by the execution of the 
RETURN on line 5200), the sum of the value of BOOK% and the length of 
PHONES is stored in PIGEON^. 

The same subroutine might be called again from a different point in 
the program to operate on tvro different variables: 

1500 GOSUB'lOO (BOXS, CAR%) 

Once again, the result will be stored in PIGEON^. 

While this may appear similar to the scheme of dummy variables used in 
defining user-defined functions (refer to Section 4.4.2), there is one 
very important difference. Dummy variables in function definitions 
have no significance beyond the function definition itself. Therefore 
the function can use a name as a dummy variable even if it is also 
used as a regular ("non-dummy") variable elsewhere in the program, 
without affecting the value of that variable. The arguments used in 
defining a DEF FN' subroutine, however, are regular variables that are 
not in any way distinct from those used in the main program. If a 
variable used in a main program is also used in a DEF FN' subroutine, 
the original value of that variable is lost when the DEF FN' 
subroutine is called. Consider the following examples: 

Program 1 : 

100 DUM = 1 
200 X = 16 


300 DEF HALF ROOT(DUM) 
400 Y = HALF ROOT(X) 
500 PRINT DUM, X, Y 

= SQR(DUM)/2 

/* 

/* 

FUNCTION DEFINITION */ 
SUBROUTINE CALL */ 

The output is: 




1 16 

2 
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Program 2 : 






100 DUM = 1 

200 X = 16 

300 GOSUB’lOO (X) 

400 PRINT DUM, X, Y 
500 DEF FN'IOO (DUM) 
600 Y = SQR(DUM)/2 
700 RETURN 


/* SUBROUTINE CALL */ 

/* BEGINNING OF HALF-ROOT SUBROUTINE */ 
/* END OF SUBROUTINE */ 


The output is: 

16 16 2 


In the first program, DUM is used to define the function HALF_ROOT, 
which is then called to operate on the value of X. Afterwards, DUM 
retains the value it v/as assigned in line 100. In the second program, 
DUM is again used to define the same operation (lines 500, 600). When 
the subroutine is called in line 300, however, DUM is assigned the 
value of X, thereby destroying the value originally assigned in line 
100 . 


Arguments are passed in the exact order in which they appear in the 
argument lists: the first item in the GOSUB' list to the first item 
in the DEF FN' list, the second to the second, and so on. Arguments 
must correspond in type; an alphanumeric argument cannot be passed to 
a numeric receiver, and vice versa. Floating-point arguments can, 
however, be passed to integer receivers, and vice versa. 


6.4.3 Program Function Keys 

The VS workstation has 16 Program Function (PF) keys at the top of the 
keyboard. You can press each key alone or with the SHIFT key, 
providing a total of 32 program functions. VS BASIC can program any 
of the PF keys to invoke the marked subroutines. 

Subroutines invoked from the keyboard are marked by DEF FN' 
statements, with the restriction that the DEF FN' numbers for 
subroutines accessible by the PF keys must be between 1 and 32 
(instead of 0 to 255, as with the GOSUB' statement). A DEF FN' 
subroutine can be invoked from the keyboard whenever execution has 
been temporarily halted by a STOP (when the compiler option 
MINANS = NO is selected) or INPUT statement. At this time, pressing a 
PF key causes control to pass to the DEF FN' subroutine corresponding 
to that PF key. For example, 

500 STOP 




2000 DEF FN'l 
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Pressing PFl when execution is halted by the STOP at line 500 invokes 
the subroutine marked by DEF FN'l. Pressing ENTER causes the normal 
sequence of execution to continue with the statement following STOP. 
Pressing a PF key for which there is no corresponding DEF FN' 
subroutine in the program causes the workstation alarm to sound; the 
key is ignored. 

Keyboard subroutines operate in the same manner as GOSUB' subroutines, 
with one exception. A RETURN statement passes control back to the 
STOP or INPUT statement, instead of to the following statement. Thus, 
DEF FN' subroutines can be invoked repeatedly from a STOP or INPUT 
statement. 


NOTE 


To avoid unintended transfers to marked subroutines, it is recommended 
that numbers 1 through 32 be used only for those subroutines meant to 
be invoked by PF keys. 


6.5 EXTERNAL SUBROUTINES 

A second class of subroutines is not contained in the body of the 
program (the same file), but instead resides in a separate file. Such 
subroutines, referred to as external subroutines or subprograms, are 
defined with the SUB statement and invoked with the CALL statement. 

In general, a VS BASIC source file can contain either a main program 
or a subprogram. Subprograms are distinguished from main programs by 
the fact that the first statement of a subprogram, other than a 
comment, is the SUB statement. 


6.5.1 Operation of External Subroutines 

The SUB statement declares a program to be a subroutine and specifies 
the subroutine name, allowing it to be referenced in CALL statements. 
The CALL statement transfers control from one program (the calling 
program) to the beginning of another program (the external 
subroutine). The external subroutine is referenced using the name 
specified in the SUB statement. The point at which the CALL statement 
occurs in the main program is saved, so that control can later return 
to that point. A subroutine can contain one or more CALL statements 
with which it can call other subroutines. A subroutine cannot call 
itself. 

When control is passed to an external subroutine by a CALL statement, 
the normal sequence of execution is followed in the subroutine until 
an END statement is encountered. Control then returns to the 
statement following the last CALL statement executed. 
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Execution of a CALL statement invokes an entire sequence of statements 
from the called subroutine. These called statements are invoked in 
the same sequence as they appear in the subroutine and do not affect 
the overall flow of control in the calling program. 

In both form and operation, external subroutines are self-contained 
programs. They must, however, begin with the SUB statement and, in 
some cases, operate on values obtained from the calling program. Once 
the external subroutine has been called, the only way execution can 
pass back to the calling program is by executing an END statement. 

All branching instructions (GOTO, IF...THEN...ELSE, GOSUB, GOSUB’, 
etc.) in an external subroutine refer to line numbers or statement 
labels within that subroutine. For example, it is not possible to 
GOTO a statement outside the subroutine. Note that this differs from 
internal subroutines, which can branch to any portion of the calling 
program. 


6.5.2 Form of External Subroutine Calls and Definitions 


An external subroutine is any VS BASIC program having a SUB statement 
as its first statement (other than comment). The general form of the 
SUB statement is: 

SUB "name" [ [ADDR] (arg[, arg] ... ) ] 

where "name" is the name of the subroutine, consisting of any string 
of one to eight alphabetic or numeric characters (including @, #, and 
$). The presence or absence of the word ADDR specifies the way in 
which the optional arguments are to be passed between the calling 
program and the subroutine. 

An external subroutine is called by a CALL statement in another 
program. The general form of the CALL statement is: 

C^ALL "name" [ [ADDR] (arg[, arg]_ ) ] 

where "name" is the name specified in the SUB statement of the 
subroutine being called. Again, the word ADDR and the optional 
argument list specify the form of argument passing to be used. 


NOTE 


The name of the subroutine is defined by the literal in the SUB 
statement, not by the name of the file containing 
the subroutine. These two names need not be the same. 
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6.5.3 Compiling, Linking, and Running 


You can enter each main (calling) program and each external subroutine 
into a separate source file using the Editor. The VS BASIC compiler 
must be called separately for each program and external subroutine to 
produce an object file for each one. Therefore, in writing a program 
that uses two external subroutines, three source files are created 
(one for the calling program and one for each of the two 
subroutines). The VS BASIC compiler is then run three times (once to 
compile each of these files), resulting in three object files. 

Before the program and subroutines can be run, you must link the 
object programs. Linking is the process of merging multiple object 
modules into one. The LINKER utility is used to link programs and 
external subroutines. The Linker is run from the VS Command Processor 
menu; it resolves subroutine name references betv/een object modules to 
produce a single object module that can then be run. The Linker asks 
you for the names of all the object files to be linked together and 
then requests a name for the single output file. The files are then 
linked and the final output file is generated. 

The original program and subroutines can then be run from the Command 
Processor menu as one would run any other program, using the program 
name specified as the output file for Linker. For further details on 
how to use Linker, refer to the VS Program Development Tools manual. 


6.5.4, Passing Values to External Subroutines 

Since calling programs and external subroutines are written and 
compiled as separate programs, there must be a way to pass data 
between them if subroutines are to process any of the data used in a 
calling program. In VS BASIC, values are passed in one of two ways: 

1. The values can be made arguments of the subroutine. An argument 
of a subroutine is a value that can be operated on by the action 
of the subroutine. Arguments are enclosed in parentheses 
following both the CALL and the SUB statements. 

2. The values can be stored as common variables (or ’’placed in 
common”). Common variables are variables that are stored in a 
particular area of memory accessible to all programs and 
subroutines that are run together. Variables are placed in common 
using the COM statement (refer to the COM statement entry in Part 
II). 
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The arguments in a SUB statement must be variables, array designators, 
or file numbers. These arguments are dummy variables (like those in 
user-defined function definitions; refer to Section 4.4.2) that 
indicate the names that will be used in the subroutine to refer to the 
arguments specified by any particular CALL to that subroutine. The 
actual names used for dummy variables are significant only within the 
subroutine and need have no connection v/ith names used in a calling 
program, except for type correspondence, described in Section 6.5.6. 

Arguments of a CALL statement must be numeric or alpha expressions, or 
file expressions. Their values are passed one-by-one to the dummy 
variables in the SUB statement of the external subroutine at run 
time. The value of the first expression in the CALL argument list is 
passed to the first dummy variable in the SUB statement, the second to 
the second, and so on. 

Values are passed back to the calling program when the subroutine 
ends, provided the arguments in the CALL statement are receivers. A 
subroutine cannot manipulate or examine any value used in the calling 
program unless it is passed through an argument list or common 
storage. For example. 

Calling program : 

100 A = 10 : X = 500 
200 CALL "DOUBLE”(A) 

300 PRINT A, X 

Subroutine : 

100 SUB "DOUBLE"(X) 

200 X = 2 * X 
300 END 

Output : 

20 500 

Note that although both programs use variables called X, only the 
value of A is passed to the subroutine's X since it is the only 
argument specified in the CALL statement. The subroutine's X is a 
dummy variable that, in this case, is temporarily assigned the value 
of A. The subroutine doubles the value of the argument (in this case, 
A) and then passes this value back to the calling program when the 
subroutine ends. The value of the variable called X in the calling 
program remains unchanged. 
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When an array or an alphanumeric value is used as an argument of an 
external subroutine call, BASIC normally passes a descriptor of the 
value to the subroutine, rather than the actual value. A descriptor 
is a set of data that specifies: 

1. The type of the argument (alpha scalar, alpha array, integer 
array, or floating-point array). 

2. The length of the value if it is alphanumeric (element length if 
an alpha array). 

3. The dimensions of the argument if it is an array. 

4. The address in memory at which the value is stored (a "pointer" to 
the value). 

This scheme of passing descriptors betv/een calling programs and 
subroutines is normally used when VS BASIC subroutines are called from 
VS BASIC programs. Subroutines and calling programs written in other 
languages (e.g., COBOL, Assembly) use a different scheme in which only 
the address of the value is passed. To enable VS BASIC programs and 
subroutines to be linked and run with programs and subroutines written 
in either BASIC or some other language, two forms of CALL and SUB are 
available. 

1. Non-ADDR Form — The standard BASIC argument-passing scheme that 
passes/accepts the descriptors constructed for arrays and 
alpha-expressions. With this form, any dimensions or lengths 
specified within the SUB program are ignored, since they are 
specified by the descriptors. Only the vector/matrix/scalar 
distinction is significant. Examples: 

700 CALL "INVOICE" (PN^(), Q%()) 

100 SUB "INVOICE" (PART_N0%(), QUANTITY%()) 

2. ADDR Form — Generally used when either the calling program or the 
subprogram is non-VS BASIC. Its effect differs depending on the 
statement in which it is used: 

CALL: The ADDR form of CALL causes all argument-passing to be 

done via pointers to the actual values; descriptors are not 
constructed. This method of argument-passing properly 
passes argiaments to non-BASIC (e.g., COBOL) programs, which 
always assume that there are pointers directly to the 
data. Example: 

900 CALL "PLOT" ADDR (H$, V$) 
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SUB: The ADDR form of SUB causes the program to assume that 

argument-passing was done as described in CALL (i.e., 
without descriptors). (For example, such calling may have 
been done from a COBOL program.) This implies, however, 
that the dimensions and lengths used must be those 
specified within the SUB subroutine. Thus, these 
dimensions and lengths (or defaults, if omitted) are 
significant, unlike in the non-ADDR form. Example: 

100 SUB "PLOT" ADDR {X$, Y$) 

200 DIM X$ 100, Y$ 100 


NOTE 


Languages other than VS BASIC use different internal formats 

for representing numeric data. Numeric data to be passed 

between VS BASIC and non-VS BASIC program modules must be converted to 

the appropriate format. If you are planning to write VS BASIC 

programs or subprograms that call or are called by programs in other 

languages, refer to Appendix D for information on compatibility of 

numeric data formats and data conversion routines. 


Common Variables 


The COM statement can make certain variables accessible to all 
programs and subroutines that are linked and run together. A COM 
statement must appear in all of the programs and subroutines that are 
to be run together if the programs are to manipulate or examine any of 
the same data. The COM statement in each program must precede any 
reference to any variable that is to be stored in common storage. 

The COM statement consists of the word COM followed by a list of alpha 
or numeric scalar or array names. Array names can be followed by one 
or two integers in parentheses giving the dimensions of the array. If 
these dimensions are omitted, the default dimensions are ten rows by 
ten columns so long as the compiler option MINANS = NO is selected. 

Alphanumeric scalars or array names can be followed by an integer 
giving the length, in bytes, of the scalar or the elements of the 
array. If the length indicator is omitted, the default length is 16 
bytes when the compiler option MINANS = NO is selected and 18 bytes 
when MINANS = YES. For the general form of the COM statement, refer 
to Part II. 
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As is true with passed arguments, the names used for common variables 
in a subroutine need not correspond with those used in the calling 
program, except in type (e.g., integer, alpha, array, etc.). Common 
variables referenced in calling programs and subroutines are 
associated with each other by their position in the COM statements. 
This means that, in many cases, a subroutine may require a COM list 
that includes variables not actually used by the subroutine, simply to 
indicate where in the common area certain needed variables are 
stored. For example, in 

100 COM A$5, B%, C(IOO), D 
200 CALL "SUBl" 

300 CALL ’'SUBZ" 

suppose that "SUBl" is a subroutine that performs some operation on 
the 100-element array called C{) in the main program, and that "SUB2" 
operates on the other variables in the COM list (line 100). Even 
though "SUBl" does not need to access A$ and BZ, they must be 
accounted for in a COM statement so that the subroutine can find the 
100-element array in the common area. If 

100 SUB "SUBl" 

200 COM X(IOO) 

is written, the subroutine looks for the lOO-element array, called X() 
in the subroutine, at the beginning of the common area. In fact, the 
first item in the common area is a 5-byte character string, called A$ 
in line 100 of the calling program. The subroutine reads the 
beginning of A$ as the beginning of its lOO-element array, which does 
not produce the intended results when the program is run. A correct 
form for the siibroutine's COM statement is: 

200 COM M$5, N^, X(IOO) 

In this case, even though "SUBl" actually needs to use only array X{), 
it looks for it after a 5-character alpha string and an integer in the 
common area. The last item in the common area, a floating-point 
variable called D by the calling program, need not be specified in the 
subroutine COM statement since it occurs in the common area after the 
only variable needed by the subroutine. 


NOTE 


No variable name occurring in the argument list of a SUB statement can 
occur as another argument of the same SUB statement or in a COM 
statement in that subroutine. Calling programs can, however, pass 
common variables to a subroutine as arguments in a CALL statement. 
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6.5.5 Initialization of Subroutine Variables 




The variables in the argument list receive their arguments from the 
calling program when the subroutine is called. All other variables 
(local variables) are initialized when the VS BASIC program is first 
executed. String variables are initialized to all spaces when the 
compiler option MIMANS = NO and all blanks when MINANS = YES; integer 
and floating-point variables are initialized to zero. This 
initialization, however, occurs only once in the execution of a VS 
BASIC program. 

Local variables are not reinitialized on subsequent calls. One 
application of this feature is as follov/s: 

SUB "HOOPOE"(arg,arg,...) 

REM Let I be a variable that is not in the argument 
REM list above. 

IF I <> 0 THEN 700 

REM Place here statements that are to be 
REM executed only the first time the subroutine 
REM is called. 

LET I = 1 

REM The subroutine continues. 


END 

The first time the subroutine is executed, the variable I is set equal 
to zero (as are all others not in the argument list). When line 300 
is executed, the condition of the IF statement is not satisfied, and 
execution proceeds through line 400 and the following lines. In line 
600, the value of I is set to 1. On all subsequent calls to the 
subroutine, I retains this value. When line 300 is executed during a 
subsequent subroutine call, the IF condition is satisfied and the 
statements between lines 300 and 700 are skipped. 




100 

200 

250 

300 

400 

450 

500 

600 

700 




9900 
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6.5.6 Argument Types 


As discussed above, the name of an argument passed to a subroutine is 
not significant in making the connection between calling-program 
variables and subroutine variables. What is significant is the 
argument's position in the argument list or common block. Thus, the 
variable name listed first in the parentheses in the SUB statement or 
first in a COM list is the name used by the subroutine to refer to the 
first argument passed by the CALL statement or specified in the 
calling program's COM statement. The second variable name is linked 
to the second argument in the CALL statement or COM list, and so on. 
For example: 

15700 CALL "DANAUS" {A,B,C,D,E) 

100 SUB "DANAUS" {I,J,K,A,B) 

In this example, the variable name A in the subroutine refers to the 
variable D in the calling program. If the subroutine intends to 
access the calling program's variable A, it must use the symbol I. 

The same is true if variables are passed through common storage: 

100 COM A, B, C, D, E 


2300 CALL "PLUMBER" 

100 SUB "PLUMBER" 

200 COM I, J, K, A, B 

If you place a receiver in the argument list of a CALL statement, the 
subroutine can transmit a value back to the calling program by 
assigning a value to the corresponding variable in the argument list 
of a SUB statement. However, an expression of arbitrary complexity 
can appear in the argument list of the CALL statement. If the 
expression is not a receiver, the subroutine cannot return a modified 
value for that argument to the main program. 

The subroutine can use the corresponding variable from the SUB 
statement as a receiver. Doing so produces the usual effects during 
the duration of that call to the subroutine, but no detectable effects 
after the subroutine returns to the calling program. For example, 
constants, literals, and complex expressions can occur in the argument 
list of a CALL statement. This precludes the possibility of the 
subroutine's returning a value to the calling program by the use of 
that particular element. 
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Whether a receiver or an expression occurs as an argument in a CALL 
statement, its type must match the type of the corresponding argument 
in the SUB statement it calls. 


If the nth 
argument of a SUB 
statement is... 


...then the nth argument of 
any CALL statement that 
calls it must be... 


an alpha scalar, an alpha expression, 

such as: X$ 


an integer scalar, an integer expression, 

such as: 


a floating-point a floating-point expression, 

scalar: X 


an array an array-designator of the same type 

designator: X$(> (integer, string, floating-point). 


a file number: #3 a file expression selected by the 

calling program or passed to it as 
a parameter. 


Note that VS BASIC does not implicitly convert a numeric quantity in a 
CALL statement from integer to floating-point, or vice versa, to make 
its type match the type in the argument list of a SUB statement. 


Entire arrays can be passed from a calling program to a subroutine. 
Only the array designator (for example, E() or M$()) is used as an 
argiament in the CALL statement. The SUB statement must contain, in 
the corresponding position, an array designator of the same type 
(floating-point, integer, or string) as the designator in the CALL 
statement. The designator used in the SUB statement declares the name 
by which that array will be referenced in the subroutine. Subroutines 
can also access arrays used by the main program if the array is 
declared in COM statements in both programs, as with scalar variables. 

An alpha array string (refer to Section 5.3) cannot be passed to a 
subroutine in the usual manner. If the array string M$() occurred as 
an argument in a CALL statement, it is interpreted as an 
array-designator for the array M$, and not as the array string. You 
can pass an array string to a subroutine by using the expression 
STR(^()) as an argument in the CALL statement. 


NOTE 


Array strings longer than 256 bytes are truncated. 
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The number of subscripts associated with a variable must be consistent 
between the calling program and the subroutine. If the array passed 
is two-dimensional (a matrix), it must be used as a matrix in the 
subroutine. If it is one-dimensional (a vector), it must be used as a 
vector in the subroutine. A DIM statement should appear in the 
subroutine to declare each array argument as either a vector or a 
matrix. In the DIM statement, the supplied dimensions are irrelevant; 
the actual upper limits are those specified in the array descriptor 
passed from the calling program. In fact, a MAT REDIM statement 
(refer to Section 9.2.4) can occur in a subroutine, and the 
redimensioning of the matrix remains in effect v;hen control returns to 
the calling program, unless the subroutine is ADDR type (refer to 
Section 6.5.4). In that case, the effects of the MAT REDIM last only 
until control returns to the calling program. 


NOTE 


If an array whose designator appears in the SUB statement does not 
appear in a DIM statement in the subroutine, it is assumed to be a 
matrix. 


A file-expression can be passed from a calling program to a 
subroutine. For instance, if CALL "SUBR0U"(#2) calls SUB 
"SUBR0U"(#1), then the subroutine can perform input and output on file 
#1 (e.g., READ #1 or WRITE #1). The actual file used is the file that 
the calling program refers to as #2. Unless linkage is made in this 
manner, any file selected by the calling program is inaccessible to 
the subroutine, and any files selected by the subroutine are 
inaccessible to the calling program. Files can be selected by the 
subroutine whether or not a file with the same number was selected by 
the calling program. 


6.5.7 Using External Subroutines 

External subroutines may be preferable to internal GOSUB or GOSUB' 
subroutines for the following reasons: 

1. A program may be more manageable when broken down into separate 
subroutines in separate files. Division into subroutines may 
reflect the logical division of function within a program. 
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2. A file containing a subroutine can be linked in with several 
different main programs if the subroutine performs a task common 
to all the main programs. If changes are made to the subroutine, 
there is only one copy of the source file for that subroutine that 
has to be updated. You do not have to modify any of the source 
files. 

3. VS BASIC programs can call subroutines written in other languages 
as well as in VS BASIC. Subroutines can also be written in VS 
BASIC to be called by programs in other languages. Thus, the CALL 
and SUB statements form BASIC’s primary interface to other 
languages, such as COBOL and Assembler. 
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CHAPTER 7 

WORKSTATION AND PRINTER INPUT/OUTPUT 


7.1 INTRODUCTION 

VS BASIC contains a group of statements to facilitate I/O operations 
to the workstation and printer. These statements enable the program 
to receive and validate your data from the workstation, and to create 
formatted screen output for display at the workstation and formatted 
print output for the printer. (VS BASIC also supports output to the 
printer through printer files. Refer to Section 8.2.1 for a 
discussion of printer files.) 


7.1.1 Output 


The statements intended purely for data output are: 

PRINT — Use PRINT to print data on the printer, or display data at 
the workstation, one line at a time. The output device is determined 
by a SELECT statement. The data can be directed to specific positions 
on the workstation screen with the AT clause, or can be formatted with 
a USING clause and an auxiliary formatting statement (refer to Section 
7.4). The screen is not cleared before the data is displayed. For a 
general description of the PRINT statement, refer to Part II. 

DISPLAY — Use DISPLAY to direct a formatted display to the 
workstation, using the entire screen. DISPLAY clears the screen 
before beginning data output so that the new display is constructed 
only of the contents of the DISPLAY statement. The output of DISPLAY 
is intended only for the workstation screen, and cannot be directed to 
the printer. Section 7.6 describes the operation of the DISPLAY 
statement. 
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All VS BASIC input statements can also be used to some extent to 
direct data or messages to the workstation. None of this output, 
however, can be directed to the printer. You can use the INPUT and 
STOP statements to send a one-line message, but you have no control 
over data format or position on the screen. The ACCEPT statement can 
also output an entire screen of data and literal messages in the same 
manner as DISPLAY. For descriptions of the INPUT and STOP statements, 
refer to Part II of this manual. Section 7.5 discusses the ACCEPT 
statement. 


7.1.2 Input 

The statements used for data input are: 

INPUT — Use INPUT to receive data entered from the keyboard on a 
line-by-line basis. A message inserted in an INPUT statement is 
displayed before the question mark INPUT is automatically displayed. 
PF keys can be used in response to an INPUT statement to initiate a 
branch to a marked subroutine (refer to Section 6.4.3). 

ACCEPT — Use ACCEPT to create a formatted display using the entire 
screen (the screen is cleared when ACCEPT begins execution) and then 
receive and validate data entered by you in response to this 
display. Current values of receivers in an ACCEPT statement are 
displayed, and can be altered by you. ACCEPT can control the 
positioning of data and literals on the screen, as well as the format 
and Display mode of data (bright, dim, flashing, etc.). Data entered 
to an ACCEPT statement can be automatically validated by type (alpha 
or numeric) and range of values. Data not of the appropriate type or 
value is rejected and must be re-entered. ACCEPT can also perform 
branches to other statements based on the use of PF keys and on 
whether displayed data values are altered. ACCEPT cannot branch to 
marked subroutines, as INPUT can. The ACCEPT statement is discussed 
in detail in Section 7.5 and in Part II. 


7.2 PRINTER OUTPUT 


Most printers have 132 columns, numbered left to right from column 1 
through column 132. The columns are divided into seven zones. When 
the compiler option MINANS = NO is selected, zones begin in columns 1, 
19, 37, 55, 73, 91, and 109. All zones occupy 18 character positions, 
except the rightmost zone, which is 24 characters wide. When the 
compiler option MINANS = YES is selected, all zones occupy 20 
character positions and begin in columns 1, 21, 39, 57, 75, 93, and 
111. With this option, the last zone is 22 characters wide. 
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You can direct data to the printer by using the PRINT statement after 
a SELECT PRINTER statement is executed. Either literals or the 
current value of any variable or expression can be printed, using a 
wide variety of formats. 

The PRINT statement actually moves data to a line buffer for the 
printer. The contents of the line buffer are printed only when an 
implied or explicit move to the next line occurs (e.g., via the SKIP 
clause of a PRINT statement or via a PRINT statement with no trailing 
semicolon) or when data overflov/s the capacity of the line buffer. 

When the contents of the buffer have been printed, the buffer is 
cleared and restarted at the first position. 

The VS BASIC program can conclude a print operation by printing the 
contents of the line buffer v;ith or v/ithout advancing to the next line 
( line feed ). No line feed allov/s a program to overprint one line v/ith 
another. Line feeds are suppressed by ending a PRINT statement with a 
semicolon. See Part II for details. The program can also cause a 
specified number of blank lines to be fed from the printer (with the 
SKIP clause of the PRINT statement). 

Normally, if the VS BASIC program outputs more characters than fit on 
the current print line, as many characters as possible are placed in 
the line buffer, the contents of the buffer are printed, and the 
remaining characters are moved to the start of the buffer for printing 
on the next line. This is equivalent to the "wraparound" phenomenon 
in workstation output (refer to Section 7.3.1). 

Wang VS BASIC also provides expanded print capabilities. When a 
printer has been specified in a SELECT statement, double-width letters 
can be printed on a line-by-line basis. The command PRINT HEX(OE) as 
the first character of a line initiates the expanded print, which 
continues until a carriage return is encountered. The maximum number 
of expanded print characters that will fit on a line is 61. The 
carriage return automatically cancels the expanded print option. If 
multiple lines of expanded print are desired, each line must begin 
with the PRINT HEX(OE) command. 

For details on the use^bf the PRINT statement, refer to Part II. 


7.3 WORKSTATION INPUT/OUTPUT 


The workstation display contains 24 rows of 80 characters, for a total 
of 1,920 character positions. Each character position in the display 
can be referred to by its row and column number. Thus, position (1,1) 
is the first position on the top row; position (24,1) is the first 
position on the bottom row. All the positions in a row form a line. 
The PRINT statement further divides each line into zones that begin at 
columns 1, 19, 37, and 55 (these correspond to the zones used in 
printer output). 
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7.3.1 Wraparound 


Think of the entire workstation screen as one sequential record 
containing 1,920 bytes (actually, the record contains 1,924 bytes, but 
the first four are control characters normally transparent to you). 

The order of bytes is from left to right within each line, and from 
each line to the one below. Thus, a character position to the right 
of another position on the same line is thought of as being "beyond" 
the position to its left. Similarly, a character position on a 
physically lower line of the screen is beyond a character position on 
a physically higher line. 

Each line is considered to "wrap around" to the next line: column 1 
of any line is thought of as directly follov/ing column 80 of the line 
above it. Thus, if a string of characters is directed to a line on 
which there is not enough space remaining to fit the specified 
characters, as many characters as possible are displayed on the 
current line, and the rest are displayed on the next line. However, 
column 80 of line 24 (the physical end of the screen) does not wrap 
around to column 1 of line 1. 


7.3.2 Scrollinc 


If wraparound occurs when the cursor is at the end of the screen, or 
if the cursor is explicitly directed to move down one line when 
already on the bottom line of the screen, all data then displayed on 
the screen is shifted up one line. This makes the cursor appear to 
move down relative to the text on the screen. This operation is 
called an "upward scroll" or "roll-up." Similarly, a command to move 
the cursor up past the top line of the screen results in all the text 
displayed on the screen shifting down one line — a "downward scroll" 
or "roll-dovm." 


In a scroll, a new line filled with spaces (ASCII code HEX(20)) 
appears on the screen, and one line leaves the screen. The program 
cannot recover data on the line that leaves the screen. 


7.3.3 Field Attribute Characters (FACs) 

Any position on the screen can contain any 8-bit (1 byte) binary 
code. The codes from HEX(OO) to HEX(7F) represent characters that can 
be displayed on the workstation screen. HEX(20) is the "space" or 
"blank" character. HEX(OO) is also displayed as a blank. 
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The codes from HEX(80) to HEX(FF) are Field Attribute Characters 
<FACs). FACs occupy character positions, but do not display a graphic 
character. FACs define the start of a field and contain information 
that is applied to all character positions beyond it until either 
another FAC occurs or the end of the line is reached. This 
information governs the following options: 

1. Whether the field is displayed bright , dim , blinking , or 
nondisplay (i.e., displayable characters of the field will be 
suppressed). These four options are mutually exclusive. 

2. Whether an underline appears in all character positions in that 
field, or in none. 

3. Whether the field is modifiable by operator input or protected . 

4. Whether (a) no restrictions are placed on operator input, (b) 
input lowercase letters are capitalized, or (c) only digits 0 
through 9, decimal point, and minus sign are allowed as input. 

Note that this affects input only; any characters in any field 
type can be output. This information is irrelevant if the field 
was declared "protected" by option 2 above. 

Appendix F contains a list of the Field Attribute Characters. 

When BASIC programs are running, the conditions assumed at the start 
of each line are: (1) dim display, (2) not underlined, and (3) 
protected. There is an "assumed" FAC (HEX(8C)) with those 
characteristics to the immediate left of column 1 of each line. 

You can output FACs at any time by specifying the correct hexadecimal 
code in any screen I/O statement. For example, 

300 PRINT HEX(94); 

places on the screen at the current cursor position a FAC that causes 
data displayed to its right to be protected and blinking, with no 
underlining. 

The INPUT statement places a FAC (of HEX(81)) in the screen buffer to 
the left of the field where input is to occur, thus setting that field 
to "bright, no-line, modifiable, uppercase." 
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The ACCEPT statement places a FAC before each input field. This FAC 
will normally specify (1) bright display, (2) not underlined, and (3) 
modifiable. The setting of option 4 depends on the type of item to be 
entered in that field. If a string is to be entered, the setting is 
"no restrictions on input" (HEX(80)). If a floating-point number is 
to be entered, the setting is "uppercase only" (HEX(81)), to allow 
input of the plus sign {+), the minus sign {-), the period {.), and 
the letter E. If an integer is to be entered, the setting is "numeric 
only" {HEX(82)>. You can override these FAC values with a FAC clause 
in the ACCEPT statement. (Refer to Section 7.5.1.) 

Unless the input field is followed immediately by another input field, 
the ACCEPT statement places an additional FAC (HEX(8C)) at the end of 
the field to revert the display to the default settings. 


7.4 THE USING CLAUSE AND FORMAT CONTROL STATEMENTS 


The PRINT statement and a number of file I/O statements (refer to 
Section 8.4) can use an auxiliary statement to define the format of 
data for output or input. This format-control option is specified by 
including a USING clause, which contains the line number or statement 
label of either an FMT statement or an Image {%) statement. For 
example, 

15600 PRINT USING RADISH, list of expressions 


33200 RADISH: FMT list of format specifications 
67200 ^Output image 


73600 PRINT USING 67200, list of expressions and/or literals 

Note that the position of the FMT or % statement in the program 
relative to the statement containing the USING clause is irrelevant. 
The FMT and % (Image) statements are nonexecutable statements that 
contain formatting information for an I/O statement containing a USING 
clause. 
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r^, 7.4.1 The FMT Statement 




An FMT statement consists of the reserved word FMT, followed by a list 
of control specifications, data specifications, and literals. Control 
specifications are clauses that determine the placement of data; they 
specify tab stops, column positions, and numbers of spaces or lines to 
be skipped. Data specifications are clauses that determine the type 
and format of particular data values for input or output: alpha or 
numeric, number of digits to each side of decimal point, retention or 
suppression of leading zeros, etc. For example, 

FMT COL(IO), CH{8), XX(2), PIC{####.##) 


The control and data specifications in this statement are: 

COL(IO) Control specification indicating that the first data 

item begins at the tenth position on the workstation 
or printer line (or, if used for file I/O, the tenth 
byte of the record). 


CH{8) 

XX(2) 


Data specification for an alphanumeric character 
Character") value eight characters long. 

Control specification indicating that two spaces are 
to be skipped. 


PIC(####.##) Data specification giving an "image" or "picture" of a 
numeric value v/ith four digits to the left of the 
decimal point, and two to the right. 


(For the general form of the FMT statement and a list of the kinds of 
control and data specifications, refer to Part II.) 


7.4.2 The Image (^) Statement 

An Image (%) statement consists of the single percent sign character 
(%) followed by an image or "picture" of how the output data will 
look. Fields of pound signs (#) act as data specifications, which 
show where and how data values will be input or output. Unlike the 
FMT statement, there ^re no control specifications. The information 
that would be given by control specifications in an FMT statement is 
given in an Image {%) statement by the actual layout of the fields of 
number signs. Special editing characters in these fields indicate the 
placement of signs, decimal points, commas, exponent fields, and other 
special characters used with numeric data. Fields that describe 
separate data items must be separated by one or more spaces. (For a 
detailed description of the Image {%) statement, refer to Part II.) 

For example, 

% ### UNITS @ $####.## 
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This statement has two data specification fields and a literal. The 
first data specification field is three characters long, beginning at 
the fourth character position of the workstation or printer line 
{fourth byte of a record if used for file I/O). This is followed by 
the literal UNITS\@ and the second data specification field, eight 
characters long, beginning at the eighteenth character position 
(byte). Either alpha or numeric data is acceptable as input or output 
in either of these data specification fields. Numeric data output 
through the second will appear with two digits to the right of the 
decimal point, and a dollar sign to the left of the leftmost digit. 


7.4.3 Using FMT and Image (%) Statements 


PRINT and file I/O statements with USING clauses can contain a list of 
expressions that are to be produced as output. Starting at the 
beginning of the list, items from the list of the PRINT or file I/O 
statement must correspond with the data specifications in the FMT or 
Image (%) statement. Thus, to print a numeric value followed by an 
alpha value through an FMT statement, the FMT statement must contain a 
numeric data specification followed by an alpha data specification. 

For example, 

1400 PRINT USING JUVENESCENCE, MAGNITUDE, NAME$ 

1500 JUVENESCENCE: FMT PIC(####), CH(16) 

prints the current value of MAGNITUDE using the specification 
PIC(####), and then prints the current value of NAME$ using the 
specification CH(16). Any attempt to input or output data through an 
FMT or Image (%) statement whose data specifications do not match 
those of the data actually presented results in a data conversion 
error at runtime. If the error is caused by a PRINT statement, 
execution halts and an error message is displayed. If caused by a 
file I/O statement, the branch indicated in the data error exit clause 
(refer to Section 8.6) is taken; if no data error exit was specified, 
execution halts with an appropriate error message. 

If there are more items in the PRINT or file I/O statement than there 
are data specifications in the FMT or Image {%) statement, the FMT or 
Image {%) statement is reused as many times as necessary to 
accommodate the remaining items in the list of the I/O statement. An 
error message occurs if a PRINT or file I/O statement with a non-null 
argument list is used in conjunction with an FMT or Image {%) 
statement containing no data specifications. In PRINT USING, 
subsequent output occurs on the next line down unless the item in the 
PRINT USING statement that exhausted the FMT or Image {%) statement 
was followed by a semicolon. 
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If there are more data specifications in the FMT or Image {%) 
statement than there are items in the PRINT or file I/O statement, the 
remainder of the FMT or Image statement is ignored. The I/O operation 
ends at the first data specification without a matching item from the 
I/O statement. This situation can also occur when an FMT or Image {%) 
statement is reused, but contains more data specifications than there 
are items remaining in the I/O statement. 

For example, 

1100 XYZ -###.## 

1400 PRINT USING 1100, E, F, G 

displays the current contents of E using the Image then the 

literal "XYZ”, and then the current contents of F, using the image 

Now G remains in the PRINT USING list, but the Image {%) 
statement is exhausted. Therefore, the process begins again. Since F 
and G are separated by a comma instead of a semicolon, subsequent 
display occurs on the next line down. G is printed using the image 
-### and XYZ is printed on the same line. Printing stops here, since 
there are no more arguments to use the next data specification. 


7.5 THE ACCEPT STATEMENT 


ACCEPT is the most versatile of the VS workstation I/O commands. A 
single ACCEPT statement displays a formatted screen of data at the 
workstation, which can include literal messages as well as the values 
of numeric and alpha expressions. You can enter new values for 
receivers that is displayed on the screen. Note that ACCEPT processes 
an entire screen full of data at one time, instead of one line at a 
time, as is done by INPUT. An ACCEPT statement consists of the word 
ACCEPT, followed by a list of items to be displayed on the workstation 
screen. A single ACCEPT statement can perform any or all of the 
following functions, depending on how you use the various optional 
clauses: 

1. Display literal messages. 

2. Display current values of variables and alpha receivers in an 
optionally specified format (PIC, CH clauses). 

3. Control placement of displayed literals and receivers (AT clause). 

4. Control Display mode of displayed receivers (FAC clause). 

5. Accept modifications to the values of displayed receivers. 

6. Validate modifications to receivers to confirm that they are 
within a specified range of values (RANGE clause). 
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7. Accept input from PF keys (KEYS, KEY clauses). 

8. Branch to different places in a program depending upon your 
response to the ACCEPT statement (ON and NOALT clauses). 

For the general form of the ACCEPT statement, refer to Part II. 
Sections 7.5.1 through 7.5.4 illustrate the use of each of the 
optional clauses by example. 


7.5.1 Screen Formatting 


Fields 

When an ACCEPT statement is executed, the entire screen is cleared and 
a screen is displayed containing items specified in the ACCEPT 
statement. The items that can be displayed are literal messages, 
numeric variables, and alpha receivers. Unless you specify otherwise, 
nev/ values can be entered for variables and alpha receivers by typing 
over the displayed values. You cannot modify displayed literals. 

Each item that is displayed occupies a field on the CRT screen. A 
field is a sequence of adjacent character positions on the workstation 
screen that is associated with a particular item in an ACCEPT 
statement. The width of each field is equal to the number of 
characters required to display the item. In the case of literals, 
this is simply the length of the literal itself. For alpha receivers, 
use the defined length as the field width unless some other width is 
specified with a CH clause. Field width for numeric variables is 18 
characters unless some other width is specified with a PIC clause. 

ACCEPT shows the field that a variable or alpha receiver occupies by 
displaying all blank spaces in the field as pseudoblanks. These 
appear on the screen as solid squares, and are shown in the following 
examples as underscores. For example, 

100 A = 99 

200 B$ = "BOTTLES" 

300 ACCEPT A, B$, "OF BEER ON THE WALL." 

400 PRINT A, B$ 

generates a screen containing the line 

99 BOTTLES OF BEER ON THE WALL. 
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The value of A is displayed in a field 18 characters wide: a leading 
pseudoblank is shown where a minus sign would be displayed if the 
value were negative, followed by the digits 99, followed by 15 
trailing pseudoblanks. Since B$ was not explicitly dimensioned, it 
has a default length of 16 characters. Thus, 9 pseudoblanks are shown 
following BOTTLES. The literal OF BEER ON THE WALL is displayed 
exactly as written, with no pseudoblanks. Note that a space is 
displayed before the beginning of each field. This space contains a 
Field Attribute Character (refer to Section 7.3.3). 

Positioning Data on the Screen: The AT Clause 

Use the AT clause to position a field anywhere on the screen by 
specifying the row and column of the screen at which a particular 
field begins. In the example above, the first value was displayed 
starting at the second column of the first row; the first column of 
every row is inaccessible for displaying data, since it always 
contains a FAC. By changing line 300 to 

300 ACCEPT AT (12, 25), A, B$, AT (13, 25), "BEER ON THE WALL." 

the following appears in the center of the screen (starting at the 
twenty-fifth column of rows 12 and 13): 

_99_ BOTTLES_ 

OF BEER ON THE WALL. 

If no AT clause is specified for a field, the field is positioned 
according to the default rules specified under the ACCEPT statement in 
Part II. 


Controlling Display Attributes for a Field: The FAC Clause 

In addition to controlling the position of literal and receiver fields 
on the screen, the ACCEPT statement allows you to specify the display 
attributes of a field. The display attributes determine whether a 
field is: dim, bright, blinking, or not displayed; modifiable or 
protected; containing uppercase, n\imeric, or all characters; 
underlined or not underlined. Display attributes are controlled by 
displaying a Field Attribute Character immediately preceding a field. 
For example, in the example above, changing line 300 to 

300 ACCEPT AT (12,25), A, FAC(HEX(91)), B$, AT (13,25), ! 

350 "OF BEER ON THE WALL." 

causes the same message as before to be displayed, except that the B$ 
field (containing the string BOTTLES) blinks, since HEX(91) is the FAC 
specifying blink, modifiable, uppercase, no line. 
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If the display attributes for a particular field are not explicitly 
defined with a FAC clause, the following defaults are used: 


Alphanumeric 

- Bright, modifiable, uppercase, no 
underline (HEX(81)). 

Floating-point 

- Bright, modifiable, uppercase, no 
underline (HEX(81)). 

Integer 

Bright modifiable, numeric only, no 
underline (HEX(82)). 


Note that FACs cannot be specified for literal fields, which are 
always shov/n preceded by a FAC of HEX(AC) (dim, protect, all, no line). 


Format Images of Displayed Receivers: The PIC and CH Clauses 

It is often useful to be able to display modifiable data fields in 
formats other than the default formats described in the preceding 
list. This can be done with the PIC clause for numeric fields and 
with the CH clause for alpha fields. Each of these optional clauses 
appears directly after the receiver it modifies in the ACCEPT 
statement, separated from the receiver by a comma. The PIC clause 
specifies a format image for numeric data, and the CH clause specifies 
a field width in characters. (For a description of all the editing 
characters that can be used in a PIC clause, refer to the discussion 
of this clause under the FMT statement in Part II.) For example, if 
you know that the variable A will never require more than three 
character positions to be displayed, the statement 

300 ACCEPT AT (12,20),A,PIC(###),B$,CH(7), "OF BEER ON THE WALL." 
will display 

_99 BOTTLES OF BEER ON THE WALL. 

on line 12 of the workstation screen. Note that the A and B$ fields 
no longer contain trailing pseudoblanks. 


7.5.2 Data Entry and Validation 


Data Entry 

When an ACCEPT screen is first displayed, the cursor is positioned at 
the first character of the first modifiable field. New values for any 
numeric variables or alpha receivers can be entered by typing over the 
displayed values in the appropriate fields, provided that the field 
has not had a PROTECT FAC placed before it. 
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The cursor control keys (the four keys on the workstation marked with 
arrows) move the cursor to different fields on the screen, as do the 
TAB, BACK TAB, and NEW LINE keys. TAB moves the cursor to the 
beginning of the next modifiable field, BACK TAB moves it to the 
beginning of the previous modifiable field, and NEW LINE moves it to 
the beginning of the next modifiable field that is not on the current 
line. All three of these keys move the cursor without affecting any 
of the values displayed on the screen. A field can be set to all 
blanks from the current cursor position to the end of the field by 
pressing the ERASE key. 

Any attempt to type over a nonmodifiable field or to otherwise type 
characters prohibited by the FAC governing a particular field causes 
the workstation alarm (a beep) to sound, and the cursor will not move. 

None of the changes made to data on the workstation screen are 
actually transmitted from the workstation to the computer until the 
ENTER key (or a PF key) is pressed, allowing you to modify data 
repeatedly until this point. When the ENTER key is pressed, the data 
displayed on the screen is transmitted from the workstation to the 
computer. Execution then continues either with the next statement or 
with optional ACCEPT clauses. 


Data Validation: The RANGE Clause 


Use the optional RANGE clause to perform automatic data validation to 
insure that data entered from the workstation falls within a specified 
range of values. A RANGE clause is inserted after the name of a 
receiver in an ACCEPT statement, separated from the receiver name by a 
comma; it applies only to that receiver. For numeric data, the range 
can be specified as being positive (RANGE(POS)), negative 
(RANGE(NEG)), or between the values of two expressions evaluated at 
runtime (RANGE(expl, exp2)). For alpha receivers, the range can be 
specified as being between the values of two alpha expressions in the 
ASCII collating sequence (RANGE(alpha-expl, alpha-exp2)); refer to 
Section 5.2.3 for a discussion of the ASCII collating sequence. 
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When ENTER is pressed during the execution of an ACCEPT statement, the 
value shown on the screen for each modifiable field is compared to the 
corresponding RANGE specification, if one exists. If any modifiable 
field contains a value that falls outside that specified, the screen 
is redisplayed with the first incorrect field blinking, and you must 
re-enter the value. When all fields satisfy their RANGE 
specifications, execution continues. For example, 

300 ACCEPT AT (12,15), A, PIC(###), RANGE(50,100), B$, CH(7), ! 

350 RANGE("BARRELS", "KEGS"), "OF BEER ON THE WALL." 

displays 

99 BOTTLES OF BEER ON THE WALL. 


If the value in the numeric field is changed to 45, the screen is 
redisplayed with that field ("45") blinking, since 45 is not within 
the specified range. Altering the value to any value between 50 and 
100 causes it to be accepted. Similarly, if BOTTLES is changed to 
LITERS, that field flashes when entered, since LITERS is not between 
BARRELS and KEGS in the collating sequence. CASES, however, is 
accepted. 




7.5.3 PF Key Usage and Program Branching 

The ACCEPT statement allows the program to respond to specified PF 
keys. When a PF key is pressed, its value can be assigned to a 
variable for subsequent testing and branching (or for use in a numeric 
expression), or it can be automatically tested by ACCEPT, initiating 
an immediate branch to another statement (ON Key clause). This 
capability is useful for writing interactive programs in which you can 
select options or issue commands from a menu (refer to Section 1.2.2). 

If any of the PF key clauses are present, they must appear after all 
of the literals, receivers, and modifying clauses. If more than one 
of these appear, they must appear in the order in which they are 
discussed in the following paragraphs. 


The KEYS Clause 


The KEYS clause specifies which of the 32 PF keys is processed by an 
ACCEPT statement. Pressing any PF key that has not been enabled by a 
KEYS clause causes the workstation alarm to sound, and the key is 
ignored. KEYS must be followed by an alpha expression in parentheses, 
which is interpreted as a list of one-byte binary values corresponding 
to the numbers of the PF keys to be accepted. Such a list can be 
specified either with the BIN function or with the HEX function. In 
the latter case, the PF key numbers must be converted to hexadecimal. 
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For example, to enable PF keys 1, 12, and 15, write either 
KEYS{BIN(1) & BIN(12) Se BIN{15)) 
or 

KEYS{HEX(OlOCOF)) 

Once any valid PF key is pressed, execution of the program continues 
and data on the screen can no longer be modified. 

The KEY Clause 


The KEY clause assigns the value of v/hatever valid PF key is pressed 
to a numeric variable, which is specified in parentheses after the 
word KEY. For example, if the clause KEY(OPTION) is in an ACCEPT 
statement, and you press PF15, the value 15 is assigned to the 
variable OPTION, and execution continues. 

The ON Key Clause 

The ON Key clause enables the program to branch to different points 
depending upon which PF key is pressed. The ON Key clause can perform 
either GOTO or GOSUB branches. In either case, the branch is taken 
without reading any changes made to the screen. As in the KEYS 
clause, ON is followed by an alpha expression that is treated as a 
list of 1-byte binary values of PF key numbers. The GOTO or GOSUB 
verb must be followed by a list of line numbers and/or statement 
labels to which branches can be made. The position of each line 
number or statement label in this list must correspond to the position 
of its associated PF key in the list of PF key numbers following the 
word ON. Thus, pressing the first PF key listed initiates a branch to 
the first line number or statement label, the second PF key to the 
second line number or label, and so on. For example, 

ON (BIN(l) & BIN{16)) GOTO 100, FINISH 

ON (BIN(5) & BIN(9)) GOSUB CATERPILLAR, BUTTERFLY 

transfers control to line 100 if PFl is pressed, to the statement 
labeled FINISH if PF16 is pressed, and to the appropriate subroutines 
if PF5 or PF9 is pressed. 


The ALT and NOALT Clauses 


When data entry to an ACCEPT statement is terminated by ENTER or a PF 
key, the ACCEPT statement can automatically determine if any field has 
been modified. Any keyboard action that is performed on a field, even 
retyping the old data or erasing pseudoblanks, indicates that the 
field has been altered. 
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Using the ALT clause to increase the efficiency and speed of screen 
processing causes the ACCEPT statement to read, validate, and transfer 
only those fields that were actually modified. 

The NOALT clause is a conditional branch clause that can perform 
either a GOTO or a GOSUB branch to a line number or a statement 
label. If this clause is included, and none of the displayed fields 
are altered, control passes to the specified line or statement. If 
any fields are altered, only those that have been altered are read, 
validated, and transferred (as with ALT), and execution continues 
without taking the specified branch. For example, 

NOALT GOTO LILLIPUT 
NOALT GOSUB 37200 

ALT and NOALT cannot both appear in a single ACCEPT. In any case, 
this v;ould be redundant, since NOALT performs the function of ALT if 
any fields are modified. 


7.5.4 Summary of ACCEPT Execution 

1. The screen is generated as described, with the cursor positioned 
at the first modifiable (or numeric-protected) field, if any are 
present. All fields contain the current values of the receivers. 

2. You can enter new values. When ENTER is keyed, or a PF key is 
pressed, the key is first checked for validity. If invalid, the 
workstation alarm sounds, and you can continue modifying or press 
another key. 

3. If the key is specified in the ON clause, the specified branch is 
taken without any field reads or verification. (The KEY variable, 
if specified, contains the key number in any case.) 

4. Otherwise, all modifiable fields (or only altered fields if ALT or 
NOALT is specified) are read/validated. Numeric fields are 
validated for proper numeric format independently of range 
validation. Although any PIC specification can be used, special 
characters (CR,DB, etc.) are not valid on input. 

If any field is invalid, its FAC is set to blinking and you must 
correct the mistake (and can further change other fields). 

Example: 

300 ACCEPT AT (12, 15), A, PIC(###), RANGE(50,100), ! 

310 ,FAC(HEX(91)), B$, CH(7), RANGE("BARRELS", "KEGS"), ! 

320 "OF BEER ON THE WALL.", ! 

330 KEYS(BIN(0) & BIN(l) & BIN(16)), KEY(OPTION), ! 

340 ON (BIN(l) & BIN(16)) GOTO START, FINISH, ! 

350 NOALT GOSUB 1700 
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7.6 


THE DISPLAY STATEMENT 




DISPLAY, like ACCEPT, clears the workstation screen and displays an 
entire formatted screen at one time. Unlike ACCEPT, however, DISPLAY 
does not accept any input either of data values or PF keys. 

DISPLAY can position data with the AT clause, and can specify formats 
of displayed numeric and alpha data with the PIC and CH clauses. 

These three clauses all operate as in ACCEPT. DISPLAY can also 
position data with the COL clause, which has the form COL(n), where n 
is an integer. COL(n) specifies that the next data item is to be 
displayed starting at the nth column of whichever row the cursor is 
currently on. 

For further details on DISPLAY, refer to the entries on DISPLAY and 
ACCEPT in Part II. 


7.7 WORKSTATION PROGRAMMING CONSIDERATIONS 


When programming output to the VS workstation, it is important to keep 
in mind that the workstation is capable of producing output much more 
quickly than you can read it. Incautious use of statements that clear 
the workstation screen can lead to output being erased from the screen 
before you can read it. For example, if two DISPLAY statements follow 
one another with few or no intervening statements, the data displayed 
by the first DISPLAY may be on the screen for only a fraction of a 
second before the second DISPLAY statement erases it. (The actual 
duration of the screen display depends on many variables at execution 
time, including how many other users are logged onto the VS, how much 
main memory is available to you, etc.) 

There are several ways to avoid this problem. You can use the SELECT 
P[d] statement to make the program pause for d/10 seconds after each 
DISPLAY or PRINT to the workstation. The pause interval remains the 
same until another SELECT PCd] is encountered, regardless of the 
amount of data displayed (and therefore regardless of the time 
required to read the screen). 

The STOP statement, when the compiler option MINANS = NO is selected, 
can be used after a DISPLAY or PRINT statement to halt execution while 
you read a screen. Execution is resumed when you press the ENTER key 
or a legal PF key (one which corresponds to a marked subroutine; refer 
to Section 6.4.3). The STOP statement displays the word STOP and an 
optional literal when it is executed. 
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Since all of the functions of the DISPLAY statement (except sounding 
the workstation alarm) can be performed by the ACCEPT statement, 

ACCEPT statements can be used to display information without 
performing any meaningful input. To allow you time to read a long 
message on the screen, one can display the message as a series of 
literals and/or expressions with the ACCEPT statement, and enable only 
the ENTER key (PFO, specified with a KEYS{BIN(0)) clause) for input. 
When the ACCEPT statement is executed, the desired message is 
displayed on the screen, and remains there until you press the ENTER 
key. 
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CHAPTER 8 

FILE INPUT/OUTPUT 




8.1 INTRODUCTION 

Programs written in VS BASIC can retrieve and store data in files 
located on magnetic disk or tape. The first part of this chapter 
(Section 8.2) provides general background information on the types of 
files supported on the VS, and their attributes and structures. Only 
that information required for the use of the BASIC file input/output 
facilities is included. If you need more information on the 
organization of VS files and on the operation of the Data Management 
System, consult the VS Operating System Services manual. The rest of 
this chapter describes the specific features of VS BASIC that 
facilitate file I/O operations, including detailed examples of using 
the most frequently used file I/O statements. 


8.2 FILES 


A file is a collection of data stored on either magnetic disk or tape, 
and identified by a file name. Files are made up of records . A 
record is the unit of all file input/output operations, and consists 
of a continuous series of bytes of data that are processed together. 

In general, a record corresponds to whatever unit of data is logically 
most convenient to process at one time. For example, in an inventory 
control program, a single record might consist of a part number, the 
quantity in stock, quantity on order, order date, price, and so on. 

An inventory file for 100 different parts would contain 100 records. 

In a file of text (for example, a VS BASIC source file), each record 
corresponds to a line of text as shown on the workstation or printer. 




File Input/Output 8-1 



8.2.1 File Types 




The VS supports four different types of disk files (consecutive, 
indexed, print, and WP files) that differ in their internal 
organization and use. The details of internal file organization for 
consecutive, indexed, and print files are transparent to you, since 
these are all managed and maintained by the Data Management System 
(DMS; refer to Section 1.3.1). The Document Access Subroutines allow 
a VS BASIC program to access VS word processing documents. This 
section contains a general discussion of the four file types. Section 
8.3 describes the VS BASIC statements that control file selection and 
use. 


Consecutive Files 

A consecutive file contains records that physically follow one another 
within a block in the same order in which they were written (a block 
is 2048 (2K) contiguous bytes of storage space). The information in a 
record does not in any way influence its position within the file. 

The position of a record relative to other records in a file depends 
only on when it was written relative to other records. 

Records in a consecutive file can be read either sequentially or by 
position. In sequential reading, your program in effect instructs the 
Data Management System to get the next record; rea.ding by position is 
equivalent to instructing DMS to retrieve the nth record. 


Indexed Files 

An indexed file is a disk file that contains records in a logical 
sequence that is not necessarily the same as the order in which the 
records were written (as would be true of a consecutive file). The 
logical sequence of records in an indexed file is determined by the 
value of the primary key of each record. A primary key is a 
designated portion of a record (the eighth through the twelfth bytes 
of each record, for example) that is used to sort the records into a 
particular ordered sequence. Each record in an indexed file must have 
a unique primary key. 

Indexed files can also have alternate keys . Like the primary key, an 
alternate key is a section (or field) of a data record of some 
designated position and length. One file can use up to 16 alternate 
keys, numbered 1 to 16. Every record in an indexed file has an 
alternate index mask associated with it; a mask is a 2-byte (16-bit) 
field that specifies which alternate keys can access that record. 
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Indexed files enable a program to access particular records according 
to primary or alternate key value. Records can be read from an 
indexed file sequentially or by key. In sequential reading, the 
program instructs DMS to get the next record in ascending primary key 
sequence. Reading by key, on the other hand, instructs DMS to get the 
record with a key equal to x. 

Indexed files are organized into data blocks and index blocks (a block 
is 2048 {2K> contiguous bytes of storage space). Data blocks contain 
the actual data records, in primary key sequence, within each block. 
The index blocks contain a list of primary key values of records in 
the file, with a corresponding list of pointers that indicate in 
which block a record with a particular key can be found. Files with 
alternate keys have a separate numbered alternate index for each 
defined alternate key field. Each alternate index contains entries 
only for those records whose alternate index masks specify that they 
are accessible by that key. 

The first time an indexed file is opened for output (i.e., when it is 
created), any records written to it must be done so in key sequence. 
Later additions to the file can be made in any order. DMS inserts the 
data records and index entries into their respective blocks at the 
appropriate points. When either an index block or a data block 
becomes full, it is split; the contents of half of the block are moved 
to an empty block. The result is two half-empty blocks instead of one 
full block. New insertions can then be made in the two blocks until 
one or both are full, and the splitting process takes place again. 


Print Files 


A print file is a disk file used to store records that are to be 
output by a printer. The records in a print file, like those in a 
consecutive file, always appear in the order in which they are 
written. In addition to the data records, print files contain printer 
control bytes that hold information affecting the physical appearance 
of print on a page (linefeed codes, page breaks, etc.). VS BASIC 
programs can write print files, but cannot read them. Print files are 
generally only read by printer Input/Output Processors (lOPs) and 
certain System Utility programs (e.g., DISPLAY). 


WP Files 


A WP file is a disk file that is organized for access by VS Word 
Processing. All WP files are consecutive files with fixed-length, 
noncompressed, 256-byte records. WP files include VS word processing 
documents and OIS files that reside on the VS for use within VS Word 
Processing. OIS files can only be read by VS Word Processing or the 
COPYOIS utility; however, VS BASIC programs can access VS word 
processing documents. 
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Because WP files do not conform to standard DMS file structures, a VS 
BASIC program cannot directly manipulate VS word processing documents 
through VS BASIC I/O statements. The VS Document Access Subroutines, 
described in the VS Programmer*s Guide to VS/IIS , are provided with 
the VS Word Processing software to allow program access to VS word 
processing documents in the data processing environment. The Document 
Access Subroutines allow a VS BASIC program to directly open, read, 
write, search, and print VS word processing documents. Because WP 
files do not use the standard VS BASIC I/O statements, subsequent 
discussions of I/O methods in this manual ignore WP files. 


8.2.2 Record Types: Length and Compression 


Record Length 

Files can contain records that are all of the same length 
(fixed-length records) or of differing lengths (variable-length 
records). The record length is specified in the file label of files 
with fixed-length records. In files with variable-length records, the 
length of each record is specified by a length count at the beginning 
of each record (this is maintained by DMS and is thus transparent to 
you). 


Record Compression 

You can compress variable-length records. If record compression is 
specified for a file, characters that are repeated three or more times 
consecutively are stored on the disk only once, preceded by a 
repetition factor. Compression is performed automatically by DMS when 
information is moved to the disk; compressed records are decompressed 
when the reverse transfer is performed. The entire 
compression/decompression process is completely transparent to your 
programs. Record compression can often save substantial amounts of 
disk space. 
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8.3 


USE OF FILES BY VS BASIC PROGRAMS 







All transfers of data between your programs and files, except WP 
files, are processed by the Data Management System. Your program 
communicates with DMS about the files to be used through User File 
Blocks (UFBs). A UFB contains information about fixed characteristics 
of the file it describes: whether it is a consecutive, indexed, or 
print file; the record type (fixed- or variable-length, compressed or 
not); record length; and various other factors. When a VS BASIC 
program is compiled, one UFB must be created for each file of 
particular characteristics to be used by the program. These 
characteristics are all specified in a SELECT statement, which also 
assigns a file number to a UFB. Note that since the UFB is part of 
the object program, a SELECT statement has its effect (creation of a 
UFB) at compile time. 

In addition to the fixed characteristics of a file specified with 
SELECT, there are factors relating to the way in which a file is to be 
used that are specified at runtime, and that may change during program 
execution. These include the file's name, whether it is to be used 
for input or output, and how much space is allocated for it if it is a 
nev/ file. These runtime specifications are made with the OPEN 
statement. The OPEN statement initiates a connection between your 
program and a specific file through a particular UFB by associating 
the name of the file with the file number of the UFB. This connection 
is severed by the CLOSE statement. I/O operations can be performed 
with a file only if it is open. The characteristics (file type, 
record type and length, and so on) of a file named in an OPEN 
statement must match those specified in the SELECT statement for the 
file number if the file already exists. If the file is being created, 
it is created with the characteristics described by the SELECT 
statement. 

Only one file can be opened on a particular file number at a time. 
Thus, a program must contain one UFB, and therefore one SELECT 
statement, for each file with a particular set of characteristics to 
be open at one time . For example, a program might use one consecutive 
file, one indexed file, and one printer file. In this case, it must 
have three SELECT statements, one to create each of the three 
different UFBs needed. Another program might use three consecutive 
files, each with fixed-length, 80-byte records. If no more than one 
of these files is open at one time, then the program needs only one 
SELECT statement. All three files can use the same UFB, since they 
will be open at different times. 
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8.3.1 The SELECT Statement 


The SELECT statement is made up of a series of clauses, some of which 
are optional, describing the characteristics of the file(s) that can 
be associated with a particular UFB. For the general form of the 
SELECT statement, refer to Part II of this manual. 

The elements of the SELECT statement indicate the following: 

File number — Number sign (#) followed by an integer from 1 to 64 
(inclusive). This file number is used in all other I/O statements to 
refer to the file described by this SELECT statement. It must be 
specified for each UFB to be created. 

Prname — A literal string consisting of one to eight alphabetic or 
numeric characters. It must be specified for each UFB created. The 
prname is not the filename. 

VAR[C] — Specifies that records are variable length (optionally 
compressed). If not specified, records are fixed length, with length 
specified by the RECSIZE clause. It cannot be specified for PRINTER 
files; it is optional for all other types. 

CONSEC, INDEXED, PRINTER, TAPE — Specifies file type. These are 
mutually exclusive choices; one of the four types must be specified. 
Note that a TAPE file is always consecutive in form. The word 
CONSEC, however, always indicates a consecutive disk file. 

RECSIZE = inti — Record length, in bytes, for files with 
fixed-length records. It is the maximum record length for files with 
variable-length records, and must be specified for every file, 
regardless of type. Refer to the SELECT entry in Part II for record 
length limits for each file type. 

KEYPOS = int2 — Position (starting from byte number 1) of the first 
byte of primary key in records of an indexed file. It must be 
specified for an indexed file. 

KEYLEN = int3 — Length (in bytes) of the primary key in records of 
an indexed file. It must be specified for an indexed file. 

ALT[ERNATE] KEY int4, KEYPOS - int5, KEYLEN = int6 — Number, 
position, and length of an alternate key in the records of an indexed 
file. It is optional for an indexed file. Up to 16 alternate keys 
can be specified; each must be identified by a unique key number 
(int4). ALT and ALTERNATE are equivalent forms. 

PUP — Indicates that duplicate key values are allowed for the 
alternate key specified in the preceding clause. This clause is used 
for indexed files only. If not specified for an alternate key, any 
duplicate value found for that alternate key will cause the EOD exit 
to be taken. 
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IL, ML, AL — Specifies the tape label type for TAPE files only. 

IL = IBM-type label, NL = no label, AL = ANSI Standard label. 

BLKSIZE — Specifies the size, in bytes, of the blocks into which 
TAPE files are divided. 

lOERR — Specifies a GOTO or GOSUB branch to be taken if an I/O error 
occurs on the file that is opened with the file number specified in 
the SELECT statement (refer to Section 8.3.2). It is optional for 
all file types. 

EOD — Specifies a GOTO or GOSUB branch to be taken if an end-of-data 
condition, invalid key, or duplicate key is found in a file while 
performing an I/O operation that does not have an EOD exit of its 
own. It cannot be specified for PRINTER files; it is optional for 
all others (refer to Section 8.6). 


NOTE 


The prname (parameter reference name) specified in the SELECT 
statement is not a file name. The actual name of the file to be used 
is specified in the OPEN statement. DMS uses the prname to refer to a 
file at runtime in requests for information (called GETPARMs) 
displayed on the workstation screen. Such requests appear when DMS 
requires information not specified (or incorrectly specified) in the 
program. GETPARMs are discussed more fully in Section 8.3.2. 


Note that one SELECT statement must be written for every UFB to be 
used by a program. All SELECT statements must appear in a program 
before any OPEN or file I/O statements. 

File numbers need not be selected consecutively. No file number can 
be used in more than one SELECT statement. 
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8.3.2 The OPEN and CLOSE Statements 


The OPEN statement enables input or output between a VS BASIC program 
and a file, and associates the file name with the file number of a 
particular User File Block (UFB) that has already been created by a 
SELECT statement. In all subsequent file I/O statements, the file is 
referenced by the file number in the OPEN statement. 

Use the CLOSE statement to terminate the connection between a file and 
a numbered UFB. If a file is open through a particular UFB, no other 
file can be opened through that UFB until the first file is closed. 

The format of the CLOSE statement is 

CLOSE #file-expression 

The OPEN statement can specify the name of the file or you can be 
prompted for it v/hen the OPEN is executed. In the latter case, a 
GETPARM is issued. A GETPARM is a request issued by the Data 
Management System (DMS) for information needed to perform certain 
operations. When a program is being run directly from a workstation, 
a GETPARM displays a screen specifying what information is needed. 
After you type this information into the appropriate fields on the 
screen and press the ENTER key, execution continues. If the program 
is being run from a procedure, the procedure is first prompted for the 
information. The GETPARM screen is displayed only if the procedure 
does not supply all of the necessary information, or if some of the 
information is in error (refer to the VS Procedure Language Reference 
for a discussion of procedures). 

If the file, library, and volume names are specified in the OPEN 
statement and do not need to be changed, the GETPARM prompt can be 
suppressed by specifying NOGETPARM in the OPEN statement. The prompt 
screen can be suppressed by NODISPLAY. USE NODISPLAY only if the 
correct file, library, and volume names have been specified in this or 
an earlier OPEN statement or in a procedure running the program, or if 
SET defaults are in use (refer to the VS Procedure Language Reference 
for a discussion of procedures and SET defaults). The difference 
between NOGETPARM and NODISPLAY is that the former should be used only 
if the file, library, and volume names are specified in the current 
OPEN statement. Use NODISPLAY if these specifications are omitted 
from the statement, and they can be obtained elsewhere (from an 
earlier OPEN statement, procedure, or SET defaults). 

Even if the file, library, and volume names are specified in the OPEN 
statement, the GETPARM screen is displayed if neither NOGETPARM nor 
NODISPLAY is present. In this case, you can press ENTER, which causes 
the file specified in the OPEN statement to be used. You can also 
alter the displayed file, library, and volume names. Refer to Part II 
of this manual for the general format of the OPEN statement. 


8-8 File Input/Output 



The elements in the OPEN statement indicate the following: 


MOGETPARM — Suppresses the issuing of a GETPARM for the file, 
library, and volume names. Use this only if these are specified in 
the OPEN statement. This element is optional and mutually exclusive 
with the NODISPLAY element. 

NODISPLAY — Suppresses display of a GETPARM screen for file, 
library, and volume names. An "invisible" GETPARM is issued to the 
controlling procedure if one exists or else the required information 
is obtained from this or an earlier OPEN or from the SET defaults. 
This element is optional and mutually exclusive v/ith the NOGETPARM 
element. 

File exp — Specifies a numeric expression that is evaluated to 
obtain the file number by which this file will be referenced by all 
file I/O statements. 

INPUT — Opens an existing file for input. The program can then read 
from the file, but cannot modify it. This mode is mutually exclusive 
with the I/O, Output, Extend and Shared modes. (This mode does not 
apply to print files.) Refer to Section 8.3.3. 

10 — Opens an existing file for input and output. The program is 
then able to read and modify the contents of the file. For an 
indexed file, I/O mode allows the addition of new records (like 
Extend for consecutive files). A consecutive file with fixed-length 
records can do REWRITES in I/O mode, but cannot create new records. 
This mode is mutually exclusive with the Input, Output, Extend, and 
Shared modes. (This mode does not apply to printer or tape files.) 
Refer to Section 8.3.3. 

OUTPUT — Specifies that a new file is to be created and opened for 
output, in which case records can be written out to the file, but 
cannot be read from that file. If the file existed prior to the 
OPEN, you are asked to either delete the old file or specify a new 
name. Printer files can only be opened in this mode. This mode is 
mutually exclusive with the Input, I/O, Extend, and Shared modes. 
Refer to Section 8.3.3. 

ECTEND — Opens an existing consecutive file for extension. The 
program is then able to write to the file, but not to read from it. 
The first record written is stored directly following the last record 
already in the file. This mode is mutually exclusive with the Input, 
I/O, Output, and Shared modes. (It does not apply to printer 
files.) Refer to Section 8.3.3. 



File Input/Output 8-9 



SHARED — Opens an existing file in Shared mode. This mode is 
similar to I/O mode, but allows simultaneous access to the file by 
other VS users. This mode is mutually exclusive with the Input, I/O, 
Output, and Extend modes. (Shared mode is supported only for indexed 
files and for a special type of consecutive file called a "log 
file.") Refer to Section 8.3.3. 

SPACE = expl — Specifies the approximate nuitjber of records (expl) to 
be put in the new file for Output mode files. If SPACE is omitted, a 
GiCTPARM is displayed requesting the required space information. For 
non-Output mode files, if expl is a numeric variable, it is assigned 
the number of records in the file when the file is opened. 

DPACK = exp2, IPACK = exp3 — Specifies the percentage packing 
densities of data and index blocks, respectively, for new (Output 
mode) indexed files only. The packing density determines what 
percentage of each data and index block is filled with data records 
and index entries. This affects the efficiency of disk space use and 
the number of records that can be inserted into a file before DMS 
must reorganize a file by splitting data and/or index blocks (refer 
to the discussion of indexed files in Section 8.2.2). For the most 
efficient use of disk space, set DPACK and IPACK to values equal to 
100 for files that will never have additional records inserted into 
them. Set DPACK and IPACK to values less than 100 for files that 
will have records inserted into them. 

FILE = alpha-expl, LIBRARY = alpha-exp2, VOLUME = alpha-exp3 — 
Specifies the file, library, and volume names of the file to be 
opened on the indicated file number. These will be requested in a 
GETPARM, whether or not they are named explicitly, unless MCXSETPARM 
or NODISPLAY has been specified. 

FILESEQ = exp 1 — Specifies the file sequence number. This is to be 
used only for tape files to position the Read/Write head at the start 
of the correct file number for tape files. 


8.3.3 File I/O Modes 


VS BASIC supports the following I/O modes: 

INPUT — Files opened for INPUT can be accessed only through the READ 
statement and, for consecutive files, the SKIP statement. The READ 
statement reads consecutive files from tape and consecutive or 
indexed files from the disk. 

10 — Files opened for I/O can be accessed through the READ 
statement. If the READ statement specifies the HOLD option, the 
record read can be subsequently modified using the REWRITE statement 
(or, for indexed files, either the WRITE, REWRITE, or DELETE 
statements). As with INPUT, the SKIP statement is available for 
consecutive files. 
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OUTPUT/EXTEND — Files opened for Output or Extend can be accessed 
with the WRITE statement only. Extend mode is supported only for 
consecutive disk files. 

SHARED — Shared mode disk I/O is supported only for indexed files 
and special log files. The file can be accessed v/ith the READ, 
WRITE, REWRITE, and DELETE statements. Moreover, when a program 
opens a file Shared, the HOLD option is available in the READ 
statement. This prevents other users from attempting to modify or 
delete the held record until you have modified or deleted it, have 
begun processing another record, or have closed the file. When the 
second I/O operation is completed, the HOLD is released, and other 
users can again access that record. If you modify or delete the 
record, that action takes effect before other users can access the 
record. A program can put a HOLD on only one record at a time. 


8.3.4 File I/O Buffering and the Record Area 


Associated with each open file is a data buffer, maintained by DMS, 
that serves as an intermediate storage location for data transferred 
between VS BASIC variables and the disk or tape. The size of the 
buffer is normally one block, which is equal to 2048 (2K) bytes . You 
can specify a larger buffer size with the BLOCKS clause of the OPEN 
statement. 

In addition to the DMS buffer, there is another intermediate storage 
area associated with each UFB, called the record area . The size of 
the record area is equal to the RECSIZE specified in the SELECT 
statement for that file number. 

All data transferred between programs and files must pass through both 
the DMS buffer and the record area for that file. Transfers between 
program data (receivers and expressions) and the record area, and 
between the record area and the DMS buffer, are always done one record 
at a time. Transfers between the DMS buffer and the file are always 
performed nXblocks at a time, where n equals the size of the DMS 
buffer specified in the BLOCKS clause of the OPEN statement (if BL(XIKS 
is omitted, n=l). Figure 8-1 diagrams the data transfer. 


program data <-> record area <-> DMS buffer <-> file 

(1 record ) (1 record ) (n blocks ) 
(at a time; ) (at a time; ) (at a time; ) 
(controlled by) (controlled by) (controlled by) 
(VS BASIC program) (VS BASIC program) (DMS ) 


Figure 8-1. The Data Transfer Path 
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The READ and WRITE statements, depending on which forms are used, 
cause data transfer either between the buffer and the record area, or 
between the buffer and program data, through the record area. Use GET 
and PUT statements to control transfer of data between program data 
and the record area alone. These four statements are all discussed 
more fully in Section 8.4. 

To illustrate the relation between file-to-buffer data transfer and 
buffer-to-program data transfer, consider a program that processes 
data from a consecutive file with fixed-length, 80-byte records. If a 
1-block buffer is used, reading the first record from the file loads 
the first block of the file into the data buffer. This 2K block 
contains twenty-five 80-byte records (plus 48 unused bytes; records 
never span a block). Any subsequent READ or WRITE statement that 
accesses any of the first 25 records of the file actually causes data 
transfer only between program data and the buffer area, through the 
record area. Since all of the first 25 records are already in the DMS 
buffer (which is in main memory), there is no need to perform a 
time-consuming disk or tape I/O operation for every record read or 
written. 

The first time a READ or WRITE occurs that involves a record outside 
of the first block, DMS checks to see if the contents of the buffer 
were modified (by a WRITE or REWRITE). If so, the contents of the 
buffer are rewritten to the disk or tape, replacing the original block 
on the storage device. The block containing the next desired record 
is then read into the buffer from the disk or tape. If the contents 
of the buffer were not modified, the next desired block is simply read 
into the buffer, overwriting its previous contents. 

If you set BLCXIKS =2 (or more) in an OPEN statement, data will be 
transferred two (or more) blocks at a time, instead of one at a time. 
This decreases the frequency of calls to DMS to perform time-consuming 
data transfers between main memory and a peripheral storage device, 
but increases the amount of storage space used. 

The optimal choice of buffer size in any particular case depends on 
several factors. The frequency of DMS-processed disk or tape I/O 
operations depends on record size and on the distribution of records 
to be accessed through the file, as well as on buffer size. There is 
also a tradeoff between frequency of I/O operations (decreases with 
increasing buffer size) and program memory requirements (increase with 
increasing buffer size). 

The only time you must consider the DMS buffer is when using the 
optional BLOCKS clause of the OPEN statement. Otherwise, the 
operation and existence of the DMS buffer are completely transparent 
to you. Therefore, subsequent discussions of file I/O generally refer 
to data transfers between files and record areas, ignoring the 
intervening DMS buffer. 
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8.4 THE FILE I/O STATEMENTS 

Transfer of data between VS BASIC programs and files is performed by 
five statements: READ, GET, WRITE, PUT, and REWRITE. Records in 
consecutive files can be read selectively by position in the file by 
using the SKIP statement before a READ. You can use the DELETE 
statement to remove selected records from an indexed file. READ, 
WRITE, REWRITE, SKIP, and DELETE operations can be performed on a file 
only while it is open (i.e., after an OPEN statement is executed for 
that file, and before a CLOSE). This section describes the v^ay in 
which data is transferred between the file and the record area, and 
between the record area and program data. For the general forms and 
full discussions of the various optional clauses and modes of use for 
these statements, refer to the appropriate entries in Part II of this 
manual. 


8.4.1 The READ Statement 

The READ statement causes one record to be read from the specified 
file into the record area for that file. You can use READ with or 
without a list of receivers. If a list of receivers is included in 
the READ statement, values are extracted one by one from the record 
area and assigned to the receivers, left to right. If USING is 
specified, the values are assigned according to the formats specified 
in the referenced FMT or Image i%) statement (refer to Section 7.4 and 
the FMT and Image {%) entries in Part II). Otherwise, values are 
assumed to be in internal format. If no list of receivers is present, 
one record is simply read from the file to the record area, and no 
assignments are performed. Once in the record area, a record is 
available to the GET, WRITE, and REWRITE statements. 

If the file being read is consecutive, you can use the RECORDS = n 
clause to specify that the nth record of the file is to be read. If a 
READ statement on a consecutive file does not have the RECORDS = n 
clause, the next sequential record is read. For indexed files, use 
the KEY clause to read a record with a primary or alternate key equal 
to a particular value. Refer to Part II of this manual for further 
details on the READ statement. 




File Input/Output 8-13 



8.4.2 The GET Statement 


The GET statement causes values to be extracted from the record area 
and assigned to one or more receivers. Values are extracted from the 
record area and assigned according to the format in the FMT or Image 
{%) statement (refer to Section 7.4 and the FMT and Image {%) entries 
in Part II) referenced with the USING clause, if one is present. If 
USING is not specified, values are assigned according to the 
conventions of VS BASIC's internal format. GET is generally used to 
assign values to receivers after a record is read from a file by a 
READ statement without a receiver list. If a PUT, WRITE, or REWRITE 
statement was executed more recently than the last READ, however, the 
record area contains v/hatever record was left there by the most recent 
of these statements. Refer to Part II for further details. 


8.4.3 The WRITE Statement 

The WRITE statement causes one data record to be written from the 
record area to the disk file. You can use WRITE with or without a 
list of expressions. If a list of expressions is included in the 
WRITE statement, their values are first packed into the record area. 
Note that an expression in a WRITE statement cannot contain a 
concatenation operation. If USING is specified, the values are packed 
into the record area according to the format in the referenced FMT or 
Image {%) statement (refer to Section 7.4 and the FMT and Image {%) 
entries in Part II). If USING is not specified, the values are packed 
into the record area according to the conventions of VS BASIC's 
internal format. The contents of the record area are then written to 
the specified file. 

If the WRITE statement contains no list of arguments, the current 
contents of the record area are written to the file. Generally, this 
form of the WRITE statement is used after data are written into the 
record area by a PUT statement. If a READ, WRITE, or REWRITE 
statement was executed more recently than the last PUT, however, the 
record area contains whatever was left there by the most recent of 
these statements. 

Records written to consecutive files (in Output, Shared, or Extend 
mode, as specified in the OPEN statement) are added to the end of the 
file. Records written to indexed files (in I/O mode) are inserted 
into the file at the appropriate point as determined by their primary 
key values. Refer to Part II for further details. 
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8.4.4 The PUT Statement 


The PUT statement causes the values of one or more expressions to be 
packed into the record area of the specified file. If USING is 
specified, the values are packed into the record area according to the 
format in the referenced FMT or Image {%) statement (refer to Section 
7.4 and the FMT and Image {%) entries in Part II). If USING is not 
specified, the values are packed into the record area according to the 
conventions of VS BASIC's internal format. PUT is generally used 
prior to a WRITE statement with no argument list. 


8.4.5 The REWRITE Statement 


REWRITE is like WRITE except that the record that is v/ritten to the 
file overwrites the last record read with a HOLD option, instead of 
being written to the end of a file. For a description of the HOLD 
option, refer to the entry under READ in Part II. REWRITE cannot be 
performed on consecutive files with variable-length records. Direct 
concatenation operations within the REWRITE statement are illegal. 


8.4.6 Summary of Data Flow Controlled by File I/O Statements 

Figure 8-2 illustrates the transfer of data for the READ, GET, WRITE, 
REWRITE, and PUT statements. 


Program Variables 
or Expressions 


Record 

Area 


{ DMS ) 
(Buffer) 


Disk 
or Tape 
File 


READ X (<-optional-) X <-(X) <-X 

[GET X <- X 

|(RE)WRITE X (-optional->) X-> (X)-> X 

IPUT X-> X 


Figure 8-2. 


Statement-Dependent Data Transfer Paths 


File Input/Output 8-15 












8.4.7 Data Representation in File I/O 


In using file I/O statements, it is important to keep in mind that VS 
BASIC represents numeric data in an internal format that bears no 
simple relation to the sequences of ASCII character codes used to 
represent that same data in workstation or printer I/O. Unless file 

I/O is explicitly formatted with the USING clause and Image {%) or FMT 

statements, all file I/O is performed in this internal format. While 
this is suitable for data files that are to be read only by other 
programs, do not use it for files to be directly examined by users, 
such as report or other text files. Any attempt to display or print 
numeric data from a file in internal format produces meaningless 
strings of characters on the workstation or printer. 

Data values packed into records in internal format take up the 
following amounts of space: 

•Floating-point 8 bytes 
•Integer 4 bytes 

•Alphanumeric defined length 

If any format conversions are done (i.e., if USING is specified in any 
file I/O statement), they are performed as data is transferred between 
the record area and variables or expressions in the program. Always 
read data from a file in the same format in which it was written for 
it to be properly interpreted by a VS BASIC program. 

For a discussion of the FMT and Image {%) statements, refer to Section 
7.4 and the FMT and Image {%) statement entries in Part II. 


8.5 INTRINSIC FILE I/O FUNCTIONS 


Use these four functions in expressions to retrieve information 
concerning file I/O operations: FS, KEY, MASK, and SIZE. These 
functions are discussed in Sections 8.5.1 through 8.5.4. 
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8.5.1 FS (File Expression) 




The FS function returns the file status for the most recent I/O 
operation on the specified file, as an alpha value two characters 
long. FS can assume any of the following values: 

CONSEC, TAPE, and PRINTER file I/O 

'00' 

Successful I/O operation 


•10’ 

End-of-file encountered 


'23' 

Invalid record number 


'30' 

Hardware error 


'34' 

No more room in the file 


'95' 

Invalid function or function sequence 


• 97 • 

Invalid record length 


INDEXED 

' file I/O 


o 

o 

Successful I/O operation 


■10' 

End-of-file encountered 


'21' 

Key out of sequence (WRITE statement in 

Output mode only) 

'22' 

Duplicate key 


'23' 

No record found matching specified key 


'24' 

Supplied key exceeds any key in the file 

1 (Input, I/O, or 


Shared mode) 


'34' 

No more room in the file (Output or I/O 

mode) 

'30' 

Hardware error 


'95' 

Invalid function or function sequence 


'97' 

Invalid record length 



8.5.2 KEY (File Expression [^exp]) 

The KEY function returns the value of a key field from the specified 
file's record area. The file-expression given as the argument of the 
KEY function must refer to an INDEXED file. The optional second 
expression is a key number specifying which key field is desired. If 
it is omitted or set equal to zero, the primary key is returned. 
Otherwise, the specified alternate key (as defined in the SELECT 
statement) is returned. The KEY function is typically read 
immediately following a READ statement (i.e., without an intervening 
WRITE statement). The KEY function returns an alpha value whose 
length is equal to the value of the KEYLEN parameter in the SELECT 
statement for that file. 

You can use the KEY function as a receiver in order to write into the 
"key" field in the data buffer. For example, 

3900 LET KEY(#3) = "NYC" 
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KEY is typically used in this way immediately preceding a READ, WRITE 
or REWRITE statement. Using arguments in the WRITE, REWRITE, and PUT 
statements causes data to be loaded into the data buffer. Depending 
on the size of the argument list and the position of the key field, 
loading the data buffer through arguments to WRITE, REWRITE, or PUT 
can overwrite the key written into the data buffer by the 
"LET KEY{#n) = " construction. 


8.5.3 MASK (File Expression) 

The MASK function returns the alternate key access mask for the last 
record read from the alternate indexed file specified. The result is 
a 2-byte alpha HEX value whose component bits (left to right) 
correspond to the record's available alternate keys (1 through 16). 
Bits that are "on" (binary 1) specify that the record can be read by 
those alternate key paths. The bit values can be determined by 
printing, in hexadecimal, the result of the MASK function. For 
example, if the program fragment 

300 READ #1, PLEXIPPUS$ 

400 DIM A$2 
500 A$ = MASK(#1) 

600 PRINT HEXOF(A$) 

were to read a record accessible by alternate keys 1, 3, 5, and 7, 
line 600 prints (or displays) 

AAOO 

I 1 

This represents the binary string 1010101000000000, indicating that 
the first, third, fifth, and seventh alternate keys are used in this 
record. 

You can use the MASK function as a receiver to set the alternate key 
access mask for a record that is to be written (or rewritten). For 
example, 

2300 MASK(#DESTINATION) = 6400 

causes the next record written to the specified indexed file to be 
accessible by alternate keys 2, 4, and 6 (6400 hex = 0101010000000000 
binary). All records written to this file have the same alternate key 
access mask until another mask value is assigned in this way. 


8.5.4 SIZE (File Expression) 

The SIZE function returns (as an integer) the size in characters of 
the record most recently read from the specified file. 
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8.6 


ERROR RECOVERY 


The situations under which an Input/Output instruction cannot be 
successfully completed fall into four categories: 

1. Errors handled by the VS Data Management System — There is an 
error or omission in the specification of a file, library, or 
volume name: the file was not found, the volume is not mounted, a 
name was omitted, and so on. 

2. EOD errors — There is no more data in the file to read, or an 
attempt was made to write a record with a duplicate key to an 
indexed file. These are errors corresponding to FS codes '10' 
through '24' (refer to Section 8.5.1). 

3. DATA errors — The data conversion routines failed because a 
record format was illegal; for instance, the program tried to read 
"ABC" into a numeric variable using a format such as ###. These 
are errors that occur within the VS BASIC program. Since they do 
not occur at the stage where data is actually transferred to or 
from a file, they do not change the File Status (FS) code for that 
file. 

4. lOERR errors — Other input/output errors, such as physical errors 
operating the device, record-length errors, and file boundary 
errors. These are errors corresponding to FS codes '30' through 
'97' (refer to Section 8.5.1). 

The Data Management System attempts to resolve some I/O errors of the 
first category by means of a dialogue with the workstation operator at 
the time of the error. VS BASIC allows you to specify program 
branches to be taken if a type EOD, DATA, or lOERR error occurs. 

Either a (30T0 or a GOSUB exit can be used. If GOSUB is used, a RETURN 
statement at the end of the subroutine returns program execution to 
the statement following the file I/O statement that had the error. 

To specify error branching, specify (1) the type of error situation to 
be covered (EOD, DATA, or lOERR), (2) the type of transfer of control 
to be performed (i.e., returning (GOSUB) or nonreturning (GOTO)), and 
(3) the VS BASIC line number or statement label to which control is to 
be passed. For instance, to force a returning branch to the statement 
labeled TURTLE if a data conversion error occurs, write 

DATA GOSUB TURTLE 
in the READ or WRITE statement. 
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Error branches for type lOERR errors are specified in the SELECT 
statement. Any lOERR errors that occur on a given file number must 
transfer control to a single routine. Error branches for DATA errors 
are specified in the READ or WRITE statement. Different statements 
transfer control to different service routines in the event of a data 
conversion error. Error branches for EOD error conditions can be 
specified in a SELECT statement to apply to all reads and writes under 
that file number, or they can be specified in an individual READ or 
WRITE statement to apply to errors occurring as a result of that 
individual statement. If a READ or WRITE statement has an EOD exit, 
that exit overrides any transfer of control that may have been 
specified in the SELECT statement. 

The REWRITE, PUT, and GET statements can also specify an error branch 
for DATA errors. The SKIP statement can specify an error branch for 
EOD errors (which occur if an attempt is made to skip (with the SKIP 
statement) past the limits of the file). 

If an EOD, DATA, or lOERR error occurs and the program has not 
specified an error branch, execution of the program is aborted. 

The service routines for EOD and lOERR type errors can examine the 
expression FS(#n), which returns the file status for the file 
currently open on UFB #n, to determine the exact cause of the error. 


8.7 EXAMPLES OF FILE I/O 

The following example program takes as input a consecutive file 
containing a list of names, addresses, and phone numbers. Each record 
of the file contains the following information in the indicated 
positions: 

Name: bytes 1 through 20 

Street: bytes 21 through 40 

City: bytes 41 through 50 

State: bytes 51 through 52 

Zip Code: bytes 53 through 57 

Area Code: bytes 58 through 60 

Phone: bytes 61 through 67 
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This program produces as output an indexed file containing those 
records that have their state fields (bytes 51 through 52) equal to 
"MA". 

100 SELECT #1, "INPUT", CONSEC, RECSIZE = 67, EOD GOTO NO_MORE 

200 SELECT #2, "OUTPUT", INDEXED, RECSIZE = 67, KEYPOS = 1, KEYLEN = 20 

300 DIM REC$ 67 

400 

500 /* OPEN AND CLOSE INDEXED FILE TO CREATE IT SO THAT ENTRIES CAN 
600 BE WRITTEN IN ANY ORDER */ 

700 OPEN #2, OUTPUT, SPACE = 100, FILE = "BOSTON", LIBRARY = "ADDRESS", ! 
800 VOLUME = "DATA" 

900 CLOSE #2 
1000 

1100 /* OPEN BOTH FILES */ 

1200 OPEN #1, INPUT, FILE = "USA", LIBRARY = "ADDRESS", VOLUME = "DATA" 

1300 OPEN #2, 10, FILE = "MASS", LIBRARY = "ADDRESS", VOLUME = "DATA" 

1400 

1500 GET_RECORD: 

1600 READ #1, REC$ /* READ A RECORD FROM THE CONSEC FILE */ 

1700 IF STR{REC$,51,2)<>"MA" THEN GET_RECORD /* EXAMINE STATE */ 

1800 WRITE #2, REC$ /* WRITE TO INDEXED FILE IF STATE = "MA" */ 

1900 GOTO GET_RECORD /* GET ANOTHER RECORD */ 

2000 

2100 NO_MORE: /* EXIT ROUTINE FOR EOD ON FILE #1 */ 

2200 CLOSE #1 
2300 CLOSE #2 
2400 

2500 END 

The two SELECT statements in lines 100 and 200 describe the two files 
to be used: file #1 is consecutive, file #2 is indexed; both have 
fixed-length, 67-byte records. When and if an end-of-data (EOD) 
condition occurs on file #1, control passes to the statement labeled 
NO_MORE. The primary key field for the indexed file (#2) begins at 
the first byte of each record, and is 20 bytes long. 

The first time an indexed file is opened for output (i.e., when it is 

created), any records written to it must be written in primary key 
sequence. If the records to be written to an indexed file are not in 
order the first time the file is to have data written to it, the file 

must be opened and closed in Output mode without writing any records 

to it, which creates a file with zero records in it (lines 700 through 
900). It can then be reopened in I/O mode (line 1300), which allows 
records to be written in any order. 
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NOTE 


In general, it is preferable to write records to indexed files in key 
sequence, if possible. Writing records to a new indexed file out of 
sequence is much less efficient in terms of both processor time and 
disk space, and is recommended only when it is not practical to write 
records in sequence. 


Once both files are opened, a record (REC$) is obtained from the 
consecutive file (line 1600) and the two characters of its state field 
are tested to see if they are equal to "MA" (line 1700). If so, the 
record is written to the indexed file (line 1-800); if not, the next 
record is read from the consecutive file (label GET_RECORD; line 
1500). This cycle continues until all of the records in the 
consecutive file have been read. The first READ operation after the 
last record has been read causes an EOD error condition to occur, and 
control passes to the statement labeled NO_MORE (line 2100), as 
specified in the EOD clause of the SELECT statement. Both files are 
then closed (lines 2200 through 2300), and the program ends. 

Note that the first 20 bytes (the name field) of each record are 
designated as the primary key field for the indexed file in the SELECT 
statement for that file. Any subsequent read from the file MASS by 
the primary key obtains the address records in alphabetical order of 
addressees’ names. However, they may have been written in any order; 
the order in which they were v^ritten was determined simply by the 
order of their appearance in the consecutive file, which was 
arbitrary. (The indexed file was opened and then closed without 
writing any records, and then reopened, specifically to enable the 
program to write the records in any order.) 

Sorted lists can be made at some later time based upon the telephone 
area codes and zip codes of the addressees. Such sorting is 
simplified by establishing alternate keys in the indexed file 
corresponding to the area code and zip code fields of the records. 

This can be done by changing the SELECT statement for the indexed file 
to: 

200 SELECT #2, "OUTPUT", INDEXED, RECSIZE=67, KEYP0S=1, KEYLEN=20, ! 

220 KEYP0S=1, KEYLEN=20, /* PRIMARY KEY = NAME */! 

240 ALT KEY 1, KEYPOS=58, KEYLEN=3, DUP, /* KEY 1 = AREA CODE */ ! 

260 KEY 2, KEYPOS=53, KEYLEN=5, DUP /* KEY 2 = ZIP CODE */ ! 
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The file now has two alternate indexes: alternate index 1, which 
indexes records by the 3-byte field starting at byte 58 of the record 
{the area code field, according to the previous example), and 
alternate index 2, which indexes records by the 5-byte field starting 
at byte 53 (the zip code field). Both indices allow duplicate keys 
(DUP), since there may be more than one entry with the same area or 
zip code. 


To insure that the records written to the file can be retrieved later 
by these alternate keys, the alternate key access mask must be set 
appropriately before any records are written. The usable keys are 
numbered 1 and 2. Set the binary value of the alternate key access 
mask to IIOOOOOOOQOOOOOO, which is COOO in hexadecimal (refer to the 
discussion of the MASK function in Section 8.5.4). Change line 1800 
to read: 

1800 WRITE #2, MASK=HEX(C000), REC$ 

The following program produces a consecutive file containing all the 
records from the MASS file that have their area code fields equal to 
”617" (assuming the file MASS was v/ritten with alternate keys, as 
described above): 






100 

200 

300 

400 

500 

600 

700 

800 

900 

1000 

1100 

1200 

1300 

1400 

1500 

1600 

1700 

1800 

1900 

2000 

2100 

2200 

2300 

2400 

2500 

2600 

2700 

2800 


SELECT #1, "INPUT", INDEXED, RECSIZE = 67, 

KEYPOS = 1, KEYLEN =20, /* PRIMARY KEY = NAME */ 

ALT KEY 1, KEYPOS = 58, KEYLEN = 3, DUP, /* KEY 1 = ZIP CODE*/ 

KEY 2, KEYPOS = 53, KEYLEN = 5, DUP /* KEY 2 = AREA CODE */ 
SELECT #2, "OUTPUT", CONSEC, RECSIZE =67 

DIM REC$ 67 

OPEN #1, INPUT, FILE = "MASS", LIBRARY = "ADDRESS", VOLUME = "DATA" 
OPEN #2, OUTPUT, SPACE = 200, FILE = "AREA617", LIBRARY = "ADDRESS", 
VOLUME = "DATA" 

FIRST_IN: /* GET FIRST RECORD W/ALT KEY 1 = "617" */ 

READ #1, KEY 1 = "617", REC$, EOD GOTO THE_END 
GOTO NEXT_OUT 

NEXT_IN: /* GET NEXT RECORD W/ALT KEY 1 = "617" */ 

READ #1, REC$, EOD GOTO THE_END 
IF KEY(#1,1) <> "617" THEN THE_END 

NEXT_OUT: /* WRITE THE RECORD OUT TO THE CONSEC FILE */ 

WRITE #2, REC$ 

GOTO NEXT_IN 

THE_END: 

CLOSE #1 
CLOSE #2 
END 
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In this case, the indexed file MASS is associated with the file number 
(UFB) #1. Note that the attributes specified in the SELECT #1 
statement {line 100) are exactly the same as those specified in the 
SELECT statement in the program that created the file' MASS. 

After the alternate indexed file MASS and the consecutive file AREA617 
are opened {lines 800 through 1000), records with alternate key 1 
{area code field) are read from MASS one at a time {lines 1300, 1700) 
and written to AREA617 {line 2100). Note that the program has two 
separate routines {labeled FIRST_IN and NEXT_IN) for reading the first 
and subsequent records. This is because any statement of the form 
READ #n, KEY m = alpha-exp reads only the first occurrence in the file 
of a record with alternate key m equal to alpha-exp . Any subsequent 
READ #n statement that does not specify an alternate key number reads 
the next occurrence of a record with the most recently specified 
alternate key. The most recently specified alternate key path {m) is 
the current "reference key" for a particular indexed file. To change 
the reference key for a file, it is necessary to execute a READ with a 
specified key. The primary key is considered to be key 0 {zero). 

After each record is read, its first alternate key field is examined 
{line 1900). The first time a record is read with alternate key 1 not 
equal to "617", the program branches to the statement labeled "THE 
END". Both files are then closed {lines 2600 through 2700), and the 
program ends. 

/^\ 

) 
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CHAPTER 9 

DATA CONVERSION AND MATRIX STATEMENTS 


9.1 DATA CONVERSION STATEMENTS 

VS BASIC provides an extensive set of instructions designed 
specifically to simplify the task of converting data from one format 
to another, either to interpret information in a foreign format, or to 
pack data into a more efficient format for storage or transmission. 

The statements included in this special data conversion instruction 
set are summarized as follows: 

CONVERT — Converts a numeric value to an alphanumeric character 
string, and vice versa. 

HEXPACK, HEXUNPACK — HEXPACK converts a character string 
representing hexadecimal digits into the binary equivalent of the 
digits. HEXUNPACK does the reverse. 

ROTATE[C] — Rotates the bits of a single character or a string of 
characters. 

TRAN — Utilizes a table-lookup technique to provide high-speed 
character conversion. 

These statements are discussed at length under their individual 
entries in Part II of this manual. 

In addition to these statements, other VS BASIC instructions that may 
be useful in data conversion operations include the Boolean operations 
AND, OR, XOR, and BOOLh (discussed in Section 5.7), the alphanumeric 
functions BIN and VAL (discussed in Section 5.5, Section 5.6, and 
under their entries in Part II>, and the binary arithmetic operations 
ADD and ADDC (discussed in Section 5.7 and under their entries in 
Part II). 
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9.2 


MATRIX STATEMENTS 




VS BASIC offers a set of matrix statements that perform operations on 
entire arrays. The matrix statements provide 15 built-in matrix 
operations, summarized in this section by function. Detailed 
discussions of each can be found in Part II. 


9.2.1 Matrix I/O Statements 


VS BASIC provides two matrix I/O statements: 

MAT INPUT — Allows runtime input of numeric or alphanumeric array 
values. 

MAT PRINT — Displays or prints one or more arrays. Matrices are 
printed rov/ by row. 

Both MAT INPUT and MAT PRINT allow explicit redimensioning of arrays 
(refer to Section 9.2.4). 


9.2.2 Matrix Assignment Statements 

VS BASIC provides the following matrix assignment statements: 

MAT CON — Sets every element of a numeric array to 1. 

MAT = — Replaces each element of a numeric or alphanumeric array 
with the corresponding element of a second array. The first array is 
redimensioned to conform to the second. 

MAT IDN — Causes a (square) matrix to assume the form of the 
identity matrix. 

MAT READ — Assigns values contained in DATA statements to array 
variables without referencing each member of the array individually. 

MAT TRN — Causes a numeric or alphanumeric array to be replaced by 
the transpose of a second array. The first array is redimensioned to 
correspond to the transpose of the second. 

MAT ZER — Sets every element of an array to zero. 

All of these matrix assignment statements allow explicit 
redimensioning of arrays. Refer to Section 9.2.4. 
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9.2.3 Matrix Arithmetic and Sorting Statements 

VS BASIC provides the following matrix arithmetic and sorting 
statements: 

MAT + — Adds two numeric arrays of the same dimension. 

MAT - — Subtracts numeric arrays of the same dimension. 

MAT ()* — Multiplies each element of a numeric array by an 
expression. 

MAT * — Stores the product of tv/o numeric arrays in a third array. 

MAT INV — Replaces one numeric matrix with the inverse of another. 

MAT ASORT , MAT DSOR T — Sorts one alphanumeric or numeric array in 
ascending or descending order into a second array. 

Operations are performed on numeric arrays according to the rules of 
linear algebra, and can be used for the solution of systems of 
nonsingular homogenous linear equations. Inversion of matrices can be 
done in significantly less time than is possible with ordinary BASIC 
statements. MAT operations on alphanumeric arrays can be used for 
simple and rapid I/O {input/output) and printing of alphanumeric 
material. 

Note that these arithmetic and sorting statements do not allow 
explicit redimensioning of arrays. 


9.2.4 Array Dimensioning 

Both numeric and alphanumeric arrays can be manipulated with MAT 
statements. If not dimensioned in a DIM or a COM statement, arrays 
are given default dimensions of 10 by 10 with a default alphanumeric 
element length of 16 bytes when the compiler option MINANS = NO is 
selected and from the first use of the array (i.e., 10 or 10 by 10) 
with a default length of 18 bytes when MINANS = YES. Each dimension 
can range from 1 to 32,767 with an alpha element length of 1 to 256 
bytes. 

The dimensions of an array can be changed explicitly using the MAT 
REDIM statement. This can also be done by adding the new dimensions, 
enclosed in parentheses, after the array name in any of the following 
MAT statements: 




MAT CON 
MAT IDN 
MAT INPUT 
MAT READ 
MAT ZER 
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Arrays can also be redimensioned implicitly, as shovm in the following 
example: 

100 DIM A(10,10),B(2,2),C(2,2) 

200 ... 

400 MAT A = B + C 

The array A is redimensioned at statement 400 from a lO-by-10 array to 
a 2-by-2 array. 

For alphanumeric arrays, the maximum length of each element can be 
changed by specifying the new length after the dimension 
specification. For example: 

MAT REDIM A$(2,3)10 

redimensions the array A$ to be two rov;s by three columns with the 
maximum length of each element in the array equal to 10. 


NOTE 


With either explicit or implicit redimensioning, the newly dimensioned 
array must not require more space than was required for its original 
dimensions. For numeric arrays, this implies the same {or fewer) 
elements. For alphanumeric arrays, there must be the same number (or 
fewer) characters. 


9.2.5 Matrix Statement Rules 


You must observe the following rules when using matrix statements: 

1. Each matrix statement must begin with the word MAT. 

2. Multiple matrix operations are not permitted in a single MAT 
statement. For instance, MAT A=B+C-Dis invalid. The same 
result can be achieved by using two MAT statements: MAT A = B + C 
and MAT A = A - D. 

3. Arrays that contain the result of certain MAT statements are 
automatically redimensioned; other arrays can be redimensioned 
explicitly in the MAT REDIM statement. A redimensioned numeric 
array cannot contain more elements than given in its original 
definition; a redimensioned alphanumeric array also cannot contain 
more characters than given in its original definition. 
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4. A vector (a singly-subscripted array) cannot be redimensioned as a 
matrix (a doubly-subscripted array), nor can a matrix be 
redimensioned as a vector. 

5. The same array variable cannot appear on both sides of the 
equation in matrix multiplication, matrix transposition, or matrix 
sorting. MAT C = A * B and MAT A = TRM(C) are valid MAT 
statements; MAT C = C * B and MAT B = TRN(B) are not. 
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Part II 

VS BASIC 
Statements and Functions 









The following rules are used in the syntax specifications to describe 
VS BASIC program statements and system commands: 

1. Uppercase letters (A through 2), digits (0 through 9), and special 
characters (*, /, +, etc.) must be written exactly as shown in the 
general form. 

2. Lowercase words represent items that are supplied by you. 

3. Items in square brackets ([]) indicate that the enclosed 
information is optional. For example, the general format RESTORE 
[expression] indicates that the RESTORE statement can be 
optionally followed by an expression. 

4. Braces ({}) enclosing vertically stacked items indicate 
alternatives; one of the items is required. For example, 

{ literal '| 

alpha variables 
expression j 

indicates that the operand can be either a literal, an alpha 
variable, or an expression. 

5. Ellipses (...) indicate that the preceding item can be repeated as 
necessary. For example, 

INPUT [literal,] receiver [,receiver]... 

indicates that you can add additional receivers to the INPUT 
statement as needed. 

6. You must follow the order of parameters shown in the general 
format. 
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ABS Function 


General Format: 
ABS (numeric exp) 


ABS returns the absolute value of the numeric expression specified as 
its argument. The value returned by the ABS function is of the same 
type (integer or floating-point) as the argument. 

Example : 

10 A = 47 
20 B = -A 

30 Print A, B, ABS(B) 

Result: 

47 -47 

47 
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ACCEPT Statement 


General Format: 


ACCEPT list [Jist]... [,KEYS(alpha-argl)] (,KEY(numeric variable)] 


ON aloha -desc / I / f^^nnber If/ line number \ 1 ] 

' P °esc ^qq5Ub| ^statementlabel/ [' | statementlabel/J -J 

{ NOALT /goto \ /linenumber \ y 
' ^GOSUBj ^ statement label j 


where: 


list = 


AT (exp2, exp3) 

< literal 

[FAC (lit or alpha var) 


{ num-variable [,PIC(image)][,num-spec] 
alpha-variable [,CH(int)][,alpha-spec] 



alpha-desc = BINO or HEXO. 


num-spec = RANGE 


f (POS) 

< (NEG) 

{ (exp4, exp5) 


alpha-spec = RANGE (alpha-arg4, alpha-arg5) 


image = a valid numeric image, as in FMT 

int = an integer specifying the length of the (alpha) field 

alpha-arg = literal, alpha-variable, BIN function, STR function 
lit = literal 
var = variable 


Section 7.5 discusses the ACCEPT statement in greater detail. A 
summary of the features and operation of ACCEPT follows. 

The ACCEPT statement allows workstation input of numeric and 
alphanumeric data in a field-oriented manner, using the supplied 
formatting information. You can enter both single receivers and 
arrays. 

ACCEPT uses the entire screen, clearing all unused areas. 
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Field Descriptions 


1. Numeric fields can be formatted according to the PICO 
specification. It is interpreted as in the FMT statement (refer 
to the FMT statement). If PIC<) is omitted, the numeric fields 
are 18 characters. All blanks appear on the screen as 
pseudoblanks. Pound signs (##) appear if a high-order digit is 
truncated. 

2. Alphanumeric field width is specified by CH(int), where int = 
field width. If CH is omitted, the field size defaults to the 
defined length of the alpha value. All blanks appear as 
pseudoblanks on the screen. 

Field Attribute Characters (FACs) 


1. If omitted, the following defaults are assumed: 

Alphanumeric — bright, modifiable, uppercase, no underline 
(HEX(81)). 

Floating-point — bright, modifiable, uppercase, no underline 

(HEX(81)). 

Integer — bright, modifiable, numeric only, no underline 
(HEX(82)). 

2. The first character of the alpha expression specified in the FAC 
clause (alpha-arg3) is used as the FAC character. 

Field Placement Order 


1. For single receivers, the fields are placed one at a time in order 
of appearance in the statement, or in the order implied by any AT 
clauses that are used. 

2. For arrays, the fields are arranged element by element, in the 
usual row-by-row order (like MAT PRINT). 

Field Positioning 

A field can be explicitly placed at a specified row and column on the 
screen, using the AT clause of the ACCEPT statement. If no AT clause 
is given, the field is placed according to the defaults used by 
ACCEPT. These are as follows: 

1. If the field can fit on the same line as the preceding field, it 
will follow directly after the preceding field with space for one 
FAC left between the fields. If the field in question is the 
first field on the screen (i.e., there is no preceding field), 
then it is placed by default at row 1, column 2, to leave room for 
a preceding FAC. 
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2. Any modifiable field that is too long to fit in the space 
remaining on the line containing the preceding field is placed at 
the beginning of the second column of the next line on the 
screen. A modifiable field must not be too long to fit on a 
single line. The maximum length is 79 bytes. 

3. Any protected field that is too long to fit on the same line as 
the preceding field, but is no longer than 79 bytes, is placed at 
the beginning of the second position on the following line. If it 
is longer than 79 bytes, it is placed immediately following the 
preceding field, and continues onto as many lines as necessary. 

4. If a protected field is too long to fit on the line on which it 
starts, it continues for as many lines as necessary. Each new 
line begins with a FAC with the same attributes as the FAC that 
comes at the beginning of the field, except that the user cannot 
tab to continued sections of the field. 

These rules are summarized in Table II-l. 

The following conditions are considered errors, whether they occur 
because the field was placed using an AT clause, or because the field 
was placed by the ACCEPT defaults: 

1. Any modifiable field longer than 79 bytes (too long to fit on a 
single line) 

2. Any explicitly positioned modifiable field extending beyond the 
end of the line on which it is placed 

3. Any explicitly-placed field that starts beyond the boundaries of 
the screen 

4. Any field extending beyond the end of the last line on the screen 

For arrays, the cursor automatically moves to column 2 of the next 
line on the screen after each row. 
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Table II-l. ACCEPT Field Placement Defaults 


Line Length 

Modifiable Field 

Protected Field 

Less than 79 
characters 



Fits 
on line 

Immediately follows 
previous field 

Immediately follows 
previous field 

Does not fit 
on line 

Begins on next line 

Begins on next line 

More than 79 
characters 

Not allowed 

Immediately follows 
previous field 


Validation 

Data entered by you in response to an ACCEPT screen can be validated 
by either character type or value. Character type validation is 
controlled by the FAC clause. The FAC that precedes a field 
determines which types of characters (i.e., numeric only, all 
characters, uppercase only) can be typed into that field. Attempting 
to type in any character prohibited by that field's FAC causes the 
workstation alarm to sound, and the character is ignored. 

Both numeric and alphanumeric fields can be validated by the VS BASIC 
program, according to a specified range of values, before being 
accepted. If validation fails, the first incorrect field is set to 
blinking and you are reprompted for the values. Validation is done 
via a range specification as follows: 

1. Numeric 

RANGE: POS = positive values (including zero). 

NEG = negative values only. 

Note that leading signs only are evaluated for positive 
or negative range. Trailing signs are not observed. 

exp4, exp5 = lower and upper limits, respectively, for 
the input value(s) ( inclusive ). If a negative value is 
specified for a limit, the expression must be placed in 
parentheses. 
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2. Alphanumeric 


RANGE: alpha expl, alpha exp2 = lower and upper limits. The 

ASCII collating sequence is used. 


PF Key Control 

The action taken by the program in response to ENTER and PF keys can 
be controlled by any combination of three key control clauses. 

(PF keys in ACCEPT statements do not call DEFFN' subroutines or 
strings.) If all three clauses are omitted, only the ENTER key can be 
used to respond to the ACCEPT. If any clause is present, ENTER and 
all PF keys are allowed by default, subject only to the restrictions 
of the KEYS clause if present. The three key control clauses are: 

1. KEYS — Specifies the keys that are valid for this ACCEPT; if any 
others are pressed, the workstation alarm sounds. The alpha 
expression (actual length) is used as a list of 1-byte binary 
values corresponding to the allowed PF key (ENTER = 00). Invalid 
values are ignored. (PF32 = HEX(20) may be considered to be a 
trailing blank if the user is not careful.) The key order is 
irrelevant. 

2. KEY — Causes the number of the key (ENTER = 0) you press to be 
placed in the numeric variable. This is done prior to any field 
validation or exit branching. The KEYS clause takes precedence 
over the KEY clause. 

i 

3. ON Key Value — Allows you to exit without changing any data 
values if certain PF keys are specified. As in the KEYS clause, 
the alpha expression (actual length) is treated as a PF key list. 
Each entry in the list corresponds to a line number or statement 
label to which the program branches if that PF key is pressed. Do 
not follow the last line number with a comma, and do not specify 
line numbers or statement labels. 

Response to Modification of Data 

1. Ordinarily, all modifiable fields are read, validated, and 
transferred to their receivers, whether or not you actually change 
the fields. This can be made more efficient via the ALT 
specification or the NOALT clause. The presence of either ALT or 
the NOALT exit in the ACCEPT statement causes only those fields 
that were altered by you (i.e., character keystrokes detected at 
the workstation) to be processed. Unaltered fields are ignored, 
and the corresponding receivers are unchanged. 

2. If NOALT is specified and no fields were altered, the specified 
exit is taken. 

3. If ALT is specified, only those fields that were altered are 
processed; however, an exit cannot be specified. 
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Execution of ACCEPT 


1. The screen is generated as described, with the cursor positioned 
at the first modifiable (or numeric-protected) field, if any. All 
fields contain the current values of the receivefs/array elements. 

2. You can enter new values. When ENTER is keyed, or a PF key is 
pressed, the key is first checked for validity. If invalid, the 
workstation alarm sounds. You can continue to modify or can press 
another key. 

3. If the key is specified in the ON clause, the specified branch is 
taken without any field reads or verification. (The KEY variable 
contains the key number, in any case.) 

4. Otherwise, all modifiable fields (or only altered fields if ALT or 
NOALT is specified) are read/validated. Numeric fields are 
validated for proper numeric format independently of RANGE 
validation. Although any PIC specification can be used, special 
characters (CR,DB, etc.) are not valid on input. 

If any field is invalid, its FAC is set to blinking. You must 

correct the mistake, and can further change other fields. 

Syntax Example ; 

300 ACCEPT AT (12, 15), A, PIC(###), RANGE(50,100), ! 

310 FAC(HEX(91)), B$, CH(7), RANGE("BARRELS", "KEGS"), ! 

320 "OF BEER ON THE WALL.", ! 

330 KEYS(BIN(0) & BIN(l) & BIN(16)), KEY(OPTION), ! 

340 ON (BIN(l) & BIN(16)) GOTO START, FINISH, ! 

350 NOALT GOSUB 1700 
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ADD[C] Logical Operator 


General Format; 

[LET] alpha-receiver = [logical exp] ADD[C] logical exp 
logical exp: see Section 5.7 


Use the ADD operator to add a binary value to the binary value of an 
alpha variable. For example, in the statement 

100 A$ = ADD B$ 

the binary value of B$ is added to the binary value of A$, and the 
result is stored in A$. 

If an operand is specified before the ADD operator {operand-1), its 
value is stored in the receiver variable prior to performing the 
addition. For example, in the statement 

100 A$ = C$ ADD B$ 

the value of C$ is first stored in A$; the value of B$ is then added 
to A$, and the result is stored in A$. The contents of operand-1 and 
the operand that follows the ADD operator (operand-2) are not altered. 

If C does not follow the ADD operator, the addition is carried out on 
a character-by-character basis from right to left, with no carry 
propagation between characters. That is, the rightmost byte of the 
value of the operand is added to the rightmost byte of the receiver 
variable, the next-to-last character of the operand is added to the 
next-to-last character of the receiver, and so forth. For example, 

100 DIM A$2 

200 A$ = HEX(0123) 

300 A$ = ADD HEX(OOFF) 

400 PRINT "RESULT = ";HEX0F{A$) 

results in the output: 

0122 

If the operand and receiver are not of the same defined length, the 
shorter one is left-padded with hex zeros. The result is 
right-justified in the receiver, with high-order characters truncated 
if the result is longer than the receiver. 

If C does follow ADD, the value of the operand is treated as a single 
binary number and is added to the binary value of the receiver 
variable with carry propagation between characters. 
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For example 


100 DIM A$2 ^ 

200 A$ = HEX(0123) 

300 A$ = ADDC HEX{00FP) 

400 PRINT "RESULT = ";HEX0F{A$) 

results in the output: 

0222 


Refer to Section 5.7 for more information. 


Syntax Examples : 

600 A$ = ADD HEX(FF) 

200 A$ = ADDC ALL(FF) 

900 STR(A$,1,2) = B$ ADDC C$ 
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ALL Function 


General Format: 
ALL (alpha-exp) 


The ALL function creates a string consisting entirely of characters 
equal to the first character of the alpha expression, and has a length 
equal to the defined length of the receiver. It is used only in 
logical expressions. (For more information on the use of the ALL 
function, refer to Section 5.5.) 

Syntax Examples : 

400 LET A$ = ALLC'X”) 

800 C$ = AND ALL(D$) 
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AND Logical Operator 


General Format: 

[LET] alpha-receiver = [logical exp] AND logical exp 
logical exp: see Section 5.7 


The AND operator performs a logical AND operation on two or more 
alphanumeric arguments. 

The operation proceeds from left to right. If the operand (the 
logical expression) is shorter than the receiver, the remaining 
characters of the receiver are left unchanged. If the operand is 
longer than the receiver, the operation stops v/hen the receiver is 
exhausted. 

Refer to Section 5.7 for more information on logical expression. 

Syntax Examples : 

100 A$ = AND B$ (Logically ANDs A$ and B$ and places the result 
in A$.) 

100 A$ = B$ AND C$ (Logically ANDs B$ and C$ and places the 

result in A$.> - 


Numeric Examples : 


HEX(OFOF) AND HEX(OFOF) 
HEX(OOFF) AND HEX(OFOF) 


= HEX(OFOF) 
= HEX(OOOF) 




11-12 VS BASIC Statements and Functions 




ARCCOS Function 




General Format: 
ARCCOS(numeric exp) 


The ARCCOS function returns the arccosine of its argument. This is 
the inverse function of COS. The value of the numeric expression used 
as an argument to ARCCOS must be between 0 and 1 (inclusive); 
otherwise, an error message results when the ARCCOS function is 
evaluated and program execution halts. ARCCOS returns a 
floating-point value in radians, degrees, or grads, depending on the 
trigonometric mode specified by the most recently executed SELECT 
statement. The default is radians if no SELECT was executed. 

Syntax Example : 

100 LET X = ARCCOS(Y) 

Numeric Examples : 

ARCCOS(O) = 90 (degrees) 

ARCCOS(l) = 0 
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ARCSIN Fxmction 


General Format: 
ARCSIN (numeric exp) 


The ARCSIN function returns the arcsine of its argument. This is the 
inverse function of SIN. The value of the numeric expression used as 
an argument to ARCSIN must be between 0 and 1 (inclusive); otherwise, 
an error message results when the ARCSIN function is evaluated and 
program execution halts. ARCSIN returns a floating-point value in 
radians, degrees, or grads, depending on the trigonometric mode 
specified by the most recently executed SELECT statement. The default 
is radians if no SELECT was executed. 

Syntax Example : 

100 LET X = ARCSIN(Y) 

Numeric Examples : 

ARCSIN(O) = 0 
ARCSIN(l) = 90 (degrees) 
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ARCTAN Function 




General Format: 
ARCTAN (numeric exp) 


The ARCTAN function returns the arctangent of its argument. This is 
the inverse function of TAN. ARCTAN returns a floating-point value in 
radians, degrees, or grads, depending on the trigonometric mode 
specified by the most recently executed SELECT statement. The default 
is radians if no SELECT was executed. 

Syntax Example : 

100 LET X = ARCTAN{Y) 

Numeric Examples : 

ARCTAN(l) = 45 (degrees) 

ARCTAN(O) = 0 
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ATN Fionction 


General Format; • 
ATN (numeric exp) 


The arctangent function; means the same as ARCTAN. 


a- ' 

<3 
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BIN Function 




General Format: 

BIN (exp [.d]) 
where: 

d = 1,2,3,4 (default = 1) 




This function converts the integer value of the expression to a 
d-character alphanumeric string that contains the binary equivalent of 
the expression, BIN is the inverse of the function VAL. 

For d = 1, 2, or 3, the expression is converted to a d-byte unsigned 
binary number. The limits for the value of the expression are: 

f 256 (d=l)| 

0 <= value expression <= "S 65536 (d=2) V 

116777216 {d=3)J 

For d = 4, the expression is converted to a 4-byte two's-complement 
signed binary number (like internal integer format). The range is 
-2147483648 <= value of expression <= 2147483647. 

Syntax Examples ; 

300 A$ = BIN(A,4) 

800 B$ = BIN(A,3) AND BIN(B,3) 

Numeric Examples : 

BIN (255,1) = HEX(FF) 

BIN (65535,2) = HEX (FFFF) 

BIN (32767,3) = HEX (007FFF) 




VS BASIC Statements and Functions 11-17 



BOOLh Logical Operator 


General Format: 

[LET] alpha-receiver = [logical exp] BOOLh logical exp 

logical exp: see Section 5.7 
h = a digit from 0 to 9, or a letter from A to F 


BOOL is a generalized logical operator that performs a specified 
operation on the value of the receiver alpha variable. The operation 
to be performed is specified by the hexadecimal digit following BOOL 
(see Table II-2). BOOL can be used only in the alpha expression 
portion of an assignment statement (i.e., on the right-hand side of 
the equal sign (=)). The value of the operand that follows the BOOLh 
operator (operand-2) and the value of the receiver variable are 
operated upon, and the result is stored in the receiver variable. For 
example, the statement 

100 A$ = BOOL7 B$ 

logically not-ANDs the value of B$ with the value of A$, and stores 
the result in A$. 

If an operand (operand-1) precedes the B(X)Lh operator, its value is 
stored in the receiver-variable prior to performing the specified 
logical operation. For example, the statement 

200 A$ = C$ BOOL7 B$ 

first stores the current value of C$ into A$, and then not-ANDs the 
value of B$ to A$. Again, the result of the operation is stored in 
A$. The contents of operand-1 and operand-2 are not affected by the 
operation. 

In every case, the logical operation to be performed is identified by 
the hexadecimal digit following B(X)L. Sixteen logical operations are 
available (see Table II-2). The hexadecimal digit used to identify 
each operation is a mnemonic that represents the logical result of 
performing the operation on the following bit combinations: 

receiver-variable: 1100 
operand-2: 1010 

For example, the hexadecimal digit E identifies the OR operation. 

When 1100 is ORed with 1010, the result is 1110, or hexdigit E. 

Several commonly used BOOL operations are available as separate 
operators: BOOLE is equivalent to OR, B(X)L6 to XOR, and B(X)L8 to AND. 
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Table II-2. Logical Operations 


BOOL 

Digit 

Logical Operation 

(Note; iff = if and only if) 



0 

null (bits always = 0; logical inverse of BOOLF) 

1 

not-OR (1 iff corresponding bits of oper*l and oper2 = 0) (NOR) 

2 

(1 iff corresponding bits of oper2 = 1 and operl = 0) 

3 

binary complement of operl (1 iff bit of operl = 0; otherwise 0) 

4 

(1 iff corresponding bits of oper2 = 0 and operl = 1) 

5 

binary complement of oper2 (1 iff bit of oper2 = 0) 

6 

exclusive OR (1 iff corresponding bits of operl and oper2 are 
different) (XOR) 

7 

not-AND (0 iff corresponding bits of both operl and oper2 = 1) 
(NAND) 

8 

AND (1 iff corresponding bits of both operl and oper2 = 1) 

9 

equivalence (1 iff corresponding bits are the same, i.e., both = 1 
or both = 0) 

A 

oper2 (identical to bits of operand 2) 

B 

operand 1 implies operand 2 (1 unless oper 1=1 and oper 2=0) 

C 

operand 1 (identical to bits of operand 1) 

D 

operand 2 implies oper 1 (1 unless oper 2=1 and oper 1=0) 

E 

OR (1 unless both corresponding bits =0) 

F 

identity (bits always = 1; logical inverse of BOOL(O)) 


* oper = operand 


BOOLS is equivalent to XOR, BOOLS is equivalent to AND, and BOOLE 
is equivalent to OR. 

Numeric Examples ; 


HEX(FOOO) = HEX(OFOF) BOOLl HEX(OFFO) 
HEX{F00F) = HEX(OFOF) BOOLS HEX(OFFO) 
HEX(FFFF) = HEX<0F0F) BOOLF HEX(OFFO) 
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CALL Statement 




General Format: 



CALL "name" [[ADDRl(arg[,arg]...)] 


where: 

"name' 

= one to eight alphanumeric characters (including @, #, S) . 

= SUB "name" of the SUB program being called 5’ 

'ifv- 

arg 

^exp ^ 

alpha-exp 
array-designator 
file-exp 



Note: 

'name" must be enclosed in quotation marks 



CALL directs execution to the named subroutine, identified by a SUB 
statement, and passes any arguments to the subroutine program dummy 
arguments. The subroutine must be linked, using the LINKER utility, 
before the program is run. This can also be done when a program is 
compiled from the Editor. 

The argijunent list in the CALL statement must correspond item-for-item 
with the argument list in the SUB statement, as shown in Tables II-3 
and II-4. 


Table II-3. Argument Correspondence 


CALL argument 

SUB argument 

(alpha-)expression 

matrix 

vector 

file-expression 

scalar variable 
matrix 
vector 
file-number 
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Table II-4. Argument Type Correspondence 


CALL argument type 

SUB argument type 

alpha 

floating-point 

integer 

alpha 

floating-point 

integer 


A SUB statement with an argument list such as 

100 SUB "HENRY" {ATLANTIS$, ELASMOBRANCH, JELLYFISH^(), #1) 

must have arguments passed to it by a CALL statement in exactly the 
same order — in this case, alphanumeric scalar, floating-point 
variable, integer array-designator, and file expression. The 
arguments in the CALL statement do not have to be identical to those 
in the SUB statement, but each must correspond to the argument in the 
same position in the SUB statement's argument list. Thus, the 
following CALL statement is valid: 

CALL "HENRY" (STR(C1$()), A<1), ), #N) 

Note that STR(C1${)) is used as a string since Cl$() would be treated 
as an alpha array designator. 

Argument passing for the CALL statement proceeds as follows: 

1. Values of file expressions are passed to the SUB program to 
replace dummy file numbers (specifically, the UFB address is 
passed to the SUB program). 

2. Pointers to the values of numeric scalar variables are passed to 
the SUB program. 

Non-ADDR Type 

Array and alphanumeric scalar descriptors are passed to the SUB 
routine, including pointers to the storage addresses, dimensions, and 
lengths. Since other numeric expressions and alpha expressions are 
not receivers, their values must be computed and stored in temporary 
locations, along with their lengths, if they are alphaniimeric. 
Pointers (in the case of numeric expressions) or descriptors of the 
temporary values (in the case of alphanumeric expressions) are then 
passed to the SUB program. Otherwise, execution proceeds as with 
arrays and receivers, except that returned values and lengths are 
effectively lost, since the locations are no longer accessible to the 
calling program. 
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ADDR Type 


All data types and pointers to the storage addresses only are passed; 
no dimensioning or length specifications are passed to the 
subroutine. (For numeric scalars and file numbers, this is identical 
to the non-ADDR type.) Changed values are accessible as with the 
non-ADDR type, except that array dimensions and lengths can be changed 
only within the subroutine (i.e., array dimensions and lengths return 
to their original values after the subroutine returns to the calling 
program). 


NOTE 


ADDR-type CALL is generally used only v/hen the called subroutine is 
non-BASIC; otherwise, standard (non-ADDR) CALLS should be used. 
(Refer to Section 6.5 for more information.) 


Syntax Examples : 

100 CALL "ELIOT"(B,C$,D%) 

200 PRINT "RETURNED" 

300 STOP 

100 DIM A$24 

200 CALL "EXTRACT" ADDR( "NA" ,A$) 
300 PRINT A$ 

400 STOP 

100 DIM LONG$100 

200 CALL "123456" (L0NG$) 

300 PRINT LONG$ 

400 STOP 
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CLOSE Statement 



This statement closes a file that was previously opened for I/O 
operations by an OPEN statement. If the file is subsequently reopened 
in the program with another OPEN statement, the file, library, and 
volume need not be respecified by you or the program. 

Attempting to close a file that was not previously opened by an OPEN 
statement causes a nonrecoverable program error at runtime. All files 
are closed at the start of the program; close opened files before the 
end of the program. 

CLOSE CRT allows you to close the workstation. This is necessary if 
you call another program that attempts to OPEN the workstation. CLOSE 
CRT is equivalent to CLOSE WS. 

Use CLOSE PRINTER to close the standard VS PRINT file selected by the 
SELECT PRINTER statement. Subsequent output to this device in the 
same rim is directed to another standard VS PRINT file. If the 
standard VS PRINT file is already closed, this statement has no effect. 

Syntax Examples ; 

100 CLOSE #1 
300 CLOSE #A 
500 CLOSE CRT 
700 CLOSE PRINTER 

PRINTER Programming Note 

On program entry, the workstation is the default output device and the 
standard VS PRINT file is closed. If a SELECT PRINTER statement is 
executed, subsequent PRINT [USING] output is directed to the standard 
VS PRINT file. This standard file is implicitly opened the first time 
any output is generated by a PRINT [USING] statement following the 
execution of the SELECT PRINTER statement. 


VS BASIC Statements and Functions 11-23 



Several standard VS PRINT files can be created during a single program 
run. These multiple files can have different Printline width 
specifications. You must execute the CLOSE PRINTER statement to 
signal the end of output to the open standard VS PRINT file, and the 
SELECT PRINTER option with a new width specified must be in effect for 
the next PRINT [USING] to be automatically routed to another standard 
VS PRINT file. Any attempt to alter the Printline width while the 
standard VS PRINT file is open produces a runtime error. To redirect 
output to the workstation, execute a SELECT CRT or SELECT WS statement. 
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COM Statement 




General Format: 

COM com element Loom element].,. 


where: 


com element = 


j numeric scalar variable 
J numeric array name (int [,int]) 
j alpha scalar variable [length-integer] 
alpha array name (int [,int]) [length-integer] 


1 < = length-integer < = 256 
1 < = int < = 32767 


The COM statement is a nonexecutable statement defining scalar 
variables or arrays to be used in common by several program segments. 
The COM statement is also discussed in Section 6.5.4. 




If a particular set of common variables is to be used in each of 
several sequentially called subprograms, the COM statement must be 
included in the main program and each subprogram in which they are 
used. All variables in the COM statements must be declared in the 
same order, and with the same dimensions and lengths, in each 
separately compiled module. 

Use the COM statement to set the maximxim defined length of 
alphanumeric variables (assumed to be 16 if not specified when the 
compiler option MINANS = NO is selected and 18 when MINANS = YES). 

The length integer {<=256) following the alpha scalar (or alpha array) 
variable specifies the length of that alpha variable (or those array 
elements). 


This statement provides array definition identical to the DIM 
statement for array variables. A single COM statement can combine 
declarations of array variables (e.g., A{10), B(3,3)) and scalar 
variables (e.g., C2,D,X$). 

You must define common variables before they are used. Therefore, it 
may be convenient to define the common variables at the beginning of 
the program. 
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Syntax Examples : 


800 COM A(10),B{3,3),C2 
200 COM C,D(4,14),E3,F(6),F1{5) 
600 COM M1$,M${2,4),X,Y 
300 COM A$10,B$(2,2)32 
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CONVERT Statement 


General Formats: 

CONVERT alpha-exp TO numeric variable 


data i i i ' 

IGOSUB I I statement label 


or 





■ # ■ 


+' 


0 



0 


- 


• 



* 

• llfU] 

++ 


1 ® 


B 



/ 



/ 




' > 



- ’ - 





line number 


CONVERT numeric exp TO alpha-receiver, PIC (image) 
where: 


image = [±][$1 \ 


where either a leading or a trailing sign can be used, but not both 


Use the CONVERT statement to convert an alphanumeric representation of 
numeric data to internal numeric format, and vice versa. Two forms of 
the statement are provided here. 

Form 1: Alpha-to-Numeric Conversion 

Form 1 of the CONVERT statement converts the number represented by 
ASCII characters in the alphanumeric expression to a numeric value and 
sets the numeric variable equal to that value. For example, if 
A$ = "1234", CONVERT A$ TO X sets X = 1234. An error results (or the 
data exit is taken) if the ASCII characters in the specified 
alphanumeric are not a legitimate VS BASIC representation of a number. 

Alpha-to-numeric conversion is particularly useful when numeric data 
is read from a peripheral device in a record format that is not 
compatible with normal VS BASIC statements, or when a code conversion 
is first necessary. It can also be useful when it is desirable to 
validate keyed-in numeric data under program control. (Numeric data 
can be received in an alphanumeric variable, and tested with the NUM 
function before conversion to numeric format.) If the alpha 
expression is entirely blank, an error results (or the data exit is 
taken). 


VS BASIC Statements and Functions 11-27 



Form 2; Numeric-to-Alpha Conversion 

Form 2 of the CONVERT statement converts the numeric value of the 
specified expression to an ASCII character string according to the 
image specified. Numeric-to-alpha conversion is particularly useful 
when numeric data must be formatted in character format in records. 

Use this form of CONVERT in the same way as a format spec in an FMT 
statement. For example, the statement 

100 CONVERT 10 to A$, PIC (####) 

results in: 




A$ = •' 10" 


Syntax Examples : 


Alpha-to-Numeric: 

100 CONVERT A$ TO X 

200 CONVERT STR(A$,1,WUM(A$)) TO X(l) 


Numeric to Alpha: 

100 X = 12.195 

200 CONVERT X TO A$, PIC (000) 

(result: A$ = "012") 

300 CONVERT X * 2 TO A$, PIC (+##.##) 
(result: A$ = "+24.39") 

400 CONVERT X TO STR(A$,3,8), PIC (-#.#?TIT) 
(result: STR(A$,3,8) = " 1.2E+01") 
500 CONVERT X TO A$, PIC (0000.#####) 
(result: A$ = "0012.19500") 
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COPY Statement 


General Format: 

COPY [-] alpha-exp TO [-] alpha-receiver 


COPY transfers the alpha expression to the alpha receiver, one byte at 
a time, using the defined lengths of both. 

If the minus sign (-) is specified before the alpha expression, the 
alpha expression is sent from right to left, starting at the rightmost 
byte of the expression. Similarly, if the minus sign (-) is specified 
before the alpha receiver, the alpha expression is received from right 
to left, starting at the rightmost byte of the receiver. 

If the minus sign (-) is not specified before the alpha expression, 
the alpha expression is sent from left to right, starting at the 
leftmost byte of the expression. Similarly, if the minus sign {-) is 
not specified before the alpha receiver, the alpha expression is 
received from left to right, starting at the leftmost byte of the 
receiver. 

Transfer stops v/hen the receiver is filled or the expression is 
exhausted. If the expression is exhausted, the remainder of the 
receiver is filled with blanks. 


NOTE 


If the alpha expression is a receiver, it is copied directly from its 
memory location; otherwise, the value of the alpha expression is 
stored in a temporary location and copied from there. Thus, copying a 
receiver onto itself can result in single-character propagation or 
other position-dependent results. 


Syntax Examples ; 


100 A$ = “CHART” 

200 COPY A$ TO B$ 
(result B$ = “CHART”) 
300 COPY -A$ TO B$ 
(result B$ = “TRAHC”) 
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cos Function 


General Format; 
COSInumeric exp) 


The COS function returns a floating-point value that is the cosine of 
the numeric expression specified as its argument. The expression is 
in units of radians, degrees, or grads, depending on the trigonometric 
mode specified by the most recently executed SELECT statement. If no 
SELECT statement was executed in the program or subprogram, the 
default mode is radians. 

Syntax Example : 

100 X = COS(Y) 

Numeric Examples : 

COS(90) = 0 (assuming the calculation is performed in degrees) 

COS(O) = 1 
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CVDQ Subroutine 






General Format: 

CALL "CVDQ" ADDR(floatbin_variable) 


The CVDQ subroutine converts the value of an input variable from the 
float binary to the float decimal representation. The CVDQ subroutine 
is useful for cases where a module compiled with float binary numerics 
must pass float values to or share a common float variable with a 
module compiled v/ith float decimal numerics. 

CVDQ returns the float decimal value to the input variable, destroying 
the previous contents of the variable. Because the float decimal 
representation has a smaller range of legal values than float binary, 
the input float binary value must be in the follov/ing range: 

-l.OE+63 < floatbin variable < l.OE+63 

Input values outside this range result in either a compile-time 
warning or a program check. In addition, positive or negative 
fractional values smaller than + lE-65 cannot be represented in float 
decimal. Input values outside this range produce an exponent 
underflow compile-time warning or runtime program check. The input 
variable must be float binary; if you pass a float decimal value to 
CVDQ, an incorrect float decimal value is returned. 

CVDQ is an external subroutine, and must be called with the ADDR form 
of the CALL statement (refer to Section 6.5.4 for details). In 
addition, programs calling CVDQ must link to the System Library 
(@SYSTEM@) on the System Volume. Consult the VS Program Development 
Tools for details on the LINKER utility. 


NOTE 


The CVDQ subroutine cannot be used on VS80 or VS50 systems, since 
these systems do not support float decimal numerics. 


Syntax Example : 

CALL “CrVDQ" ADDR(X) 
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CVQD Subroutine 


General Format: 

CALL "CVQD" ADDR(floatdec_variable) 


The CVQD subroutine converts the value of an input variable from the 
float decimal to the float binary representation. The CVQD subroutine 
is useful for cases vrhere a module compiled v/ith float decimal 
numerics must pass float values to or share a common float variable 
with a module compiled with float binary numerics. 

CVQD returns the float binary value to the input variable, destroying 
the previous contents of the variable. The entire range of float 
decimal values can be converted to float binary values. The input 
variable must be in the float decimal format; if you pass a float 
binary value to CVQD, either an incorrect float binary value is 
returned or processing terminates with a runtime DMS data exception. 

CVQD is an external subroutine, and must be called with the ADDR form 
of the CALL statement (refer to Section 6.5.4 for details). In 
addition, programs calling CVQD must link to the System Library 
(@SYSTEM@) on the system volume. Consult the VS Program Development 
Tools for details on the LINKER utility. 


NOTE 


The CVQD subroutine cannot be used on VS80 or VS50 systems, since 
these systems do not support float decimal numerics. 


Syntax Example : 

C:ALL "CVQD" ADDR(X) 
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DATA Statement 


General Format: 



, / constant 1 
^literal J 


The DATA statement provides the values to be assigned to the variables 
in a READ statement. The READ and DATA statements allow tables of 
constants to be stored within a program. 

Each time a READ statement is executed in a program, the next 
sequential value(s) listed in the DATA statements is obtained and 
stored in the receivers listed in the READ statement. The values 
entered with the DATA statement must be in the order in which they are 
to be used, and separated by commas. If several DATA statements occur 
in a program, they are used in order of statement number. Numeric 
variables in READ statements must reference numeric values; 
alphanumeric receivers must reference literals. 

When the compiler option MINANS = YES is selected, all data items are 
stored as literals and need not be enclosed in quotation marks. In 
addition, leading and trailing blanks are ignored. 

The RESTORE statement resets the current DATA statement pointer so 
that DATA statement values are reused (refer to RESTORE in this 
section). 

Example : 

100 FOR 1=1 TO 5 
200 READ W 
300 PRINT W,W**2 
400 NEXT I 

500 DATA 5, 8.26, 14.8, -687, 22 
Output: 


5 25 

8.26 68.2276 

14.8 219.04 

-687 471969 

22 484 

In the above example, the five values listed in the DATA statement are 
sequentially used by the READ statement and printed. 
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DATE Function 




General Format: 
DATE 


DATE returns a six-character string that gives the current date in the 
form YYMMDD. The DATE function takes no arguments. 

Example ; 

100 A$ = DATE 

200 PRINT STR(A$,3,2);"/";STR(A$,5,2);"/’';STR{A$,1,2) 

300 PRINT STR(DATE ,3,2);'’/”; STR( DATE, 5,2); " / "; STR(DATEl, 2) 

Output: 

09/15/82 

09/15/82 
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DEF Statement 




General Format: 

DEF function-name[%](v) = numeric exp 
where: 

function-name = Any sequence of up to 64 letters, digits, 
and underscores, provided that the first 
character is a letter, and the name is not 
a VS BASIC reserved word. 

V = The dummy variable, a numeric scalar variable and is optional 
onlylfMINANS is set to YES. 

If % is present, the function returns an /nfepervalue. 


The define statement, DEF, enables you to define a single-valued 
numeric function within the program. Once defined, this function can 
be used in expressions in any other part of the program. The function 
may provide one dummy variable whose value is supplied when the 
function is referenced. Defined functions can reference other defined 
functions, but recursion is not allowed. That is, a function cannot 
refer to itself, nor can one function refer to another function that 
refers to the first. The following program illustrates how DEF is 
used. 

The DEF statement is also discussed in Section 4.4.2. 


NOTE 


A function can be defined anywhere in a program, but if the first use 
of a function precedes its definition, the function name must begin 
with the characters FN. Otherwise, the BASIC compiler interprets the 
function call as an array name reference. This results in either an 
error message at compilation time or in logic errors in the program. 
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Example ; 

100 X = 3 

200 DEF OBFUSCATION(Z) = Z ** 2-Z 
300 PRINT X + OBFUSCATION(2 * X) 

400 END 

Output: 

33 

Processing of OBFUSCATION(2 * X> in this example proceeds in the 
following order: 

1. The expression specified as the argument of the function 
OBFUSCATION (in this case, 2 * X) is evaluated. Here, the value 
of the argument is (2* X = 6). 

2. The dummy variable in the function definition (in this case, Z in 
line 200) is temporarily assigned the value of the argument (in 
this case, 6). 

3. The expression to the right of the equal sign in the function 
definition (line 200) is evaluated given the assignment just 
performed, and the value is returned to the statement that invoked 
the function. In this case, (6 I 2-6) =30 is returned to the 
PRINT statement (line 400), which adds the value of X (3, in this 
case), and prints the result (33). 

You can invoke a user-defined function from anywhere in a program. 

The following restrictions apply to definitions of functions: 

1. A DEF function cannot refer to itself. For example, 

DEF APPLE(My_EYE) = MY_EYE + APPLE(MY_EyE) 
is illegal. 

2. Two DEF functions cannot refer to each other. For example, the 
following combination of statements is illegal: 

DEF ARTICHOKE(X) = BANANA(X) 

DEF BANANA(X) = ARTICHOKE(X) 

Neither of the above restrictions is checked for during compilation, 
but both cause endless loops resulting in "stack overflow" during 
execution. 
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The dummy scalar variable in the DEF statement can have a name 
identical to that of a variable used elsewhere in the program or in 
other DEF statements. Current values of the variables are not 
affected during function evaluation, DEF statements can also use 
other variables, using their current values at calling time. 

Syntax Examples ; 

600 DEF JAGUAR(C) ={3*A)-8*C+ LI0N(2 - A) 

700 DEF LI0N{A) =(3*A)-9/C 
800 DEF TIGER(C) = LIOM(C) * JAGUAR(2) 
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DEF FN' Statement 



The DEF FM’ statement has tv;o purposes: 

1. To define a literal to be supplied v^hen a Program Function (PF) 
key is used for keyboard text entry. 

2. To define a PF key or program entry points for subroutines with 
argument passing capability. 


Keyboard Text Entry Definition 


To be used for keyboard entry, the integer in the DEF FN' statement 
must be from 1 to 32, representing the number of a PF key. When the 
corresponding PF key is pressed while execution is halted by an INPUT 
or STOP statement, your literal(s> is displayed and becomes part of 
the currently entered text line. 


Each literal can be represented by a character string in quotes, a HEX 
function, or a combination of those elements. 




MOTE _ 

The PF keys can be defined to produce characters that do not appear on 
the keyboard by using HEX literals to specify the codes for these 
characters. 
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Syntax Examples : 


100 DEF FN'31 "April is the cruelest month." 

200 DEF FN'02 HEX(94); HEX(22);"Mistah Kurtz - he dead.";HEX{22) 

Pressing PF31 at a STOP or INPUT causes "April is the cruelest month." 
to be displayed, while pressing PF2 displays "Mistah Kurtz - he 
dead.", blinking and protected because of the HEX{94). The quotation 
marks are displayed because of the HEX(22) specifications. Thus, the 
DEF statement can be used to display characters (such as quotation 
marks surrounding character values) that are not usually displayed. 


NOTE 


When the compiler option MINANS=YES is selected, a program is 
terminated if it is first suspended by execution of a STOP statement 
followed by the pressing of a PF key. 


Marked Subroutine Entry Definition 

The DEF FN' statement, followed by an integer and an optional receiver 
list enclosed in parentheses, indicates the beginning of a marked 
subroutine. (Refer to Sections 6.4.2 and 6.4.3 for a discussion of 
marked subroutines.) The subroutine can be entered from the program 
through a GOSUB’ statement or from the keyboard by pressing the 

appropriate PF key while execution is halted by an INPUT or STOP 

statement. 

If a subroutine is to be entered through a GOSUB' statement, the 
integer in the DEF FN' statement can be any integer from 0 to 255. If 
the subroutine is to be entered from a PF key, the integer can be from 
1 to 32. When a PF key is pressed or a C30SUB’ statement is executed, 

the execution of the BASIC program transfers to the DEF FN' statement 

with an integer corresponding to the number of the PF key or with the 
integer in the GOSUB' statement (i.e., if PF2 is pressed, execution 
branches to the DEF FN'2 statement). 

When a RETURN statement is encountered in the subroutine, control 
passes to the program statement immediately following the last 
executed (30SUB* statement, or back to the INPUT or STOP statement if 
the subroutine was entered by pressing a PF key. Repeated subroutine 
calls executed without RETURN or RETURN CLEAR statements can cause 
memory overflow. (Refer to RETURN and RETURN CLEAR in this section.) 

The DEF FN' statement can optionally include a receiver list. The 
receivers in the list receive the values of arguments being passed to 
the subroutine. 
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In a GOSUB' subroutine call made internally from the program, 
arguments are listed (enclosed in parentheses and separated by commas) 
in the GOSUB' statement. If the number of arguments to be passed is 
not equal to the number of receivers in the list, a compilation error 
results. 

Example : 

100 GOSUB'2 (1.2,3+2 * X, "JOHN") 


200 STOP 

300 DEF FN'2 (A,B(3),C$) 


400 RETURN 

Result: STOP 1.2, 3.24, "JOHN" (now press PF2) 

When entering a subroutine through a PF key, arguments are passed by 
keying them in, separated by commas, immediately before pressing the 
PF key. (Refer to INPUT and STOP in this section.) If the wrong 
number or type of data is given, the entries are refused, the cursor 
returns to the beginning of the field, and the program waits for 
further operator action. 

The DEF FN' statement need not specify a receiver list. In some 
cases, it may be more convenient if the program requests you to enter 
data at a keyboard in response to prompts. 

Example : 

100 DEF FN'4 
200 INPUT "RATE",R 
300 C = 100 * R - 50 
400 PRINT "COST = ";C 
500 RETURN 

When a DEF FN' subroutine is executed through keyboard PF keys while 
the system is waiting for data to be entered into an INPUT statement 
or is in STOP mode, the INPUT or STOP statement is repeated in its 
entirety upon return from the subroutine. 
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Example : 


100 INPUT "ENTER AMOUNT",A 


200 DEF FN'l 

210 INPUT "ENTER NEW RATE",R 
220 RETURN 

Output: 

ENTER AMOUNT? 

(Press PFl) 

ENTER NEW RATE? 7.5 
ENTER AMOUNT? 

DEF FN' subroutines can be nested (i.e., they can call other 
subroutines from within a subroutine). A RETURN statement encountered 
in a nested subroutine returns execution to the subroutine that called 
the nested subroutine. 
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DELETE Statement 


General Format: 
DELETE file-exp 


The DELETE command deletes the last record read, which must be read 
with the HOLD option. It is only valid for indexed files; records in 
consecutive files cannot be deleted. 

Refer to the description of the HOLD option under the READ File 
statement. 

Syntax Example : 

100 DELETE #1 
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DIM Statement 


General Format: 

DIM dim-elt [,dim-elt]... 


where: 
dim-elt = 


{ numeric array name (inti Unt2]) 
alpha array name (inti [,int2])[int3] 
alpha scalar variable [int3] 


inti = row dimension, 1 < =int1 < =32767 
int2 = column dimension, 1 < =int2 < =32767 
int3 = string length, 1 < =int3 < =256 


The DIM statement reserves space for arrays and sets the length for 
alpha scalars or array variables. (Use of the DIM statement is also 
discussed in Section 3.5.2.) The DIM statement must appear before any 
of the dimensioned elements are used. 

If not dimensioned in a DIM statement, the following defaults hold: 

1. When the compiler option MINANS = NO is selected 

a. The string length of alpha scalar or array variables defaults 
to 16. This is also true if int3 is omitted in a DIM statement. 

b. Arrays default to lO-by-10 matrices. 

2. When the compiler option MINANS = YES is selected 

a. The string length of alpha scalar or array variables defaults 
to 18. 

b. The number of dimensions of an array is taken from its first 
usage. 

Arrays or variables dimensioned in a COM statement cannot be 
respecified in a DIM. (Refer to the discussion of the COM statement 
in this section.) A variable or array can occur in only one DIM or 
COM in each program or subprogram. 

Arrays can be redimensioned by using [MAT] REDIM. 
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Syntax Examples ; 


100 DIM A$100 

200 DIM A$(4,4),B$(12,12)20,6(3,7) 

300 DIM A(10),B$(20)10 

Note that in a DIM statement , DIM must be the first word of the 
statement. If DIM is used in any other way, it is interpreted as 
referring to the DIM function . 
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DIM Function 




General Format: 

DIM (array-designator , 



where: 

{1} = row dimension 
{2} = column dimension 


The DIM function returns, as an integer value, the current row (1) or 
column (2) dimension of the specified array. The column dimension of 
a vector is 1%. 


NOTE 


The defined length of an alpha scalar or array variable can be 
obtained using LEN{STR{variable)). 




Syntax Examples ; 

100 A = DIM(A(),1) 
200 B = DIM(A(),2) 
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DISPLAY Statement 


General Format: 

DISPLAY list Uist]... 
where: 

I COL (int) 

J AT(exp2, exp3) 

list = s numeric exp [.PIC(image)] 

I alpha-exp [,CH (int)] 

[bell 

image = a valid numeric image, as in FMT 
int = a positive integer specifying the length of the (alpha) 
field 



DISPLAY allows output of numeric and alphanumeric data values at the 
workstation in a field-oriented manner, using the supplied formatting 
information. (Refer to Section 7.6 for a detailed discussion.) Both 
single values and arrays can be displayed. 

DISPLAY works in generally the same way as ACCEPT, with the following 
exceptions: 

1. Values are written only; no new values are accepted. 

2. Pseudoblanks are not used. 

Otherwise, refer to ACCEPT. The screen is cleared prior to execution 
of a DISPLAY statement, and you should use a STOP statement to halt 
execution for viewing (if desired, and so long as the compiler option 
MINANS = NO is selected) following execution of DISPLAY. 

Refer to Chapter 7 for more information on screen I/O. 

Syntax Examples ; 

100 DISPLAY COL(10),A$,CH(20),AT(20,20),A,PIC(##.##) 

200 DISPLAY B$,BELL 
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EJECT Compiler Directive 




General Format: 
EJECT 


EJECT is a compiler directive (refer to Section 2.4.2). The EJECT 
statement, which must be the only statement on a line, causes the 
compiler to skip to the top of the next page of the source listing and 
print the most recently specified title at the beginning of the page. 

Syntax Example ; 

100 EJECT 
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END Statement 


General Format: 
END [exp] 


The END statement is required to terminate the program prior to its 
physical end or to pass a program-supplied return code to the 
operating system. You can use END anywhere and any number of times in 
the program. It is not required at the physical end of the program 
where an implied END is automatically generated. 

When the END statement is encountered, program execution terminates 
or, if it is in a subroutine, returns to the calling program. If END 
is followed by an expression, the value of the expression (truncated 
if not an integer) is passed to the operating system as a return 
code. If the expression is omitted, the return code is 0. 

Syntax Examples : 

100 END 

999 END A 

The second example passes the current (truncated) value of A to the 
system as a return code. Return codes are often useful in writing 
procedures. (Refer to the VS Procedure Language Reference for a 
discussion of procedures and the use of return codes.) 
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EXP Function 




General Format; 
EXPinumeric exp) 


The EXP (exponential) function returns a floating-point value equal to 
the natural constant "e" (the base of natural logarithms; e is 
approximately equal to 2.71828182845904) raised to the power given by 
the value of the argument. EXP is the inverse function of LOG. 

Example : 

100 A = EXP(l) 

200 B = EXP(73) 

300 PRINT A, B 

Result: 

2.718281828 5.0523936302E+31 
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FMT Statement 


General Format; 


nvi I Torm-spec 


where: 

form-spec = 


= < 


[rep-int *]data-spec 
[rep-int*]literal 
control-spec 


rep-int = integer specifying the number of times to 
repeat the data-spec or literal 


FMT is a nonexecutable statement used to format data values for PRINT 
and disk I/O statements. (Refer to Sections 7.4 and 8.4 for 
discussions of the use of the FMT statement.) The FMT statement and 
the FORM statement are synonymous and can be used interchangeably. 

They can be used wherever Image(%) is allowed, subject to the 
following restrictions; 

1. BI, FL, and PD are not displayable formats, and thus are legal 
only for disk I/O statements. 

2. For PRINT USING, the FMT statement can be reused for long argument 
lists. This is exactly like Iroage\(^), and is described in the 
PRINT section. 

A control specification (control spec) is one of the following items; 

1. XX [(int)] — Skip int positions (input) or write n blanks 
(output). If omitted, int = 1. 

2. COL (int) or POS (int) — Next form spec to start at position int 
in record or output line. (For disk I/O, int\<= record size. For 
PRINT USING, COL>80 or current printer width causes the next form 
spec to begin at column 1 of the next line.) 

3. TAB (int) — Like COL, but all skipped-over characters are set to 
blank. 

4. SKIP [(int)] — Skip int lines (default = 1). This is like PRINT 
SKIP. (This is not for disk I/O.) 
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A data specification (data spec) is one of the following items. Note 
that w and d are integer constants. 




1. CH(w) — Character data, w bytes. 

2. BI[(w)] — Binary internal format, w bytes. 1 <= w< =4, 
default = 4. 

3. FL[(w)] — Floating-point internal format, w bytes w = 4 or 8, 
default = 8. 


4. PD(w[,d]) — VS packed decimal, w digits, d digits to the right of 
the (implied) decimal point (default d=0). The value of w and d 
should be added to half the length of the replacing formatted 
integer. 


5. 


PIC([+][$] 







’+ 


0 



0 


- 


* 

B 

^... . 


* 

B 

... [ITTT] 

++ 


/ 



/ 






• 

-, - 



- 


) 


Editing Characters 




# Digit position — blank if leading zero. 

. Decimal point. 

TTTT Exponent E+xx for exponential output. If present, the digit 

positions are filled with significant digits (no leading zeros) 
and the exponent is scaled accordingly. 

* Replace leading 0 with *. 

0 Retain leading 0. 

, If right of a numeric digit, insert ; otherwise, blank. 

/ If right of a numeric digit, insert '/' ; otherwise, blank. 

B Insert blank. 




VS BASIC Statements and Functions 11-51 



Sign Trailing 


+ ’+' > 0, if < 0 

- blank if > 0, if < 0 

++ 2 blanks if > 0, ’CR' if < 0 

— 2 blanks if > 0, 'DB' if < 0 


NOTE 


You cannot specify both a leading sign and a trailing sign. If no 
signs are present, the absolute value of the number is printed. 


Sign Leading 


+ ’+' if > 0, if < 0 

blank if > 0, if < 0 

$ '$' precedes the number 


(The above three characters float to the leftmost nonzero digit 
location.) 


Syntax Examples : 

100 FMT PIC(##.##TTTt) 

200 FMT SKIP(10),CH(50),SKIP(-5),COL(20),PIC($**.##) 

NOTE 


The FMT statement always extends to the end of the line on which it 
occurs. It cannot be terminated by use of a colon (:>, as described 
in Section 2.3.2. 
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FOR Statement 








General Format: 

FOR numeric scalar variable = expl TO exp2 (STEP exp] 


The FOR and NEXT statements specify a loop. The FOR statement marks 
the beginning of the loop and defines the loop parameters. The NEXT 
statement marks the end of the loop. The program lines in the range 
of the FOR statement are executed repeatedly, beginning with 
variable = expl. The variable value is incremented by the STEP 
expression value until it exceeds the value of exp2. 

The three expressions can take on any value. If STEP is omitted, 1 is 
assumed. STEP and exp2 are evaluated only once. If STEP is 0 or has 
the wrong sign, the loop is executed only once. 

After termination of the loop, the variable has the last value used, 
i.e., without the final increment. There are no restrictions on 
branching in or out of the loop, provided that a NEXT without an open 
FOR is not encountered; this event causes an error. 

When the compiler option MINANS = YES is selected, a STEP of zero 
causes the loop to infinitely execute. Upon termination of the loop, 
the variable equals the first value not used (i.e., the last variable 
used within the loop, plus the step). Branches into the middle of a 
loop are not permitted. Additionaly, the compiler diagnoses 
mismatched FOR and NEXT statements. For instance, a FOR statement 
without a corresponding NEXT statement, and vice versa. A FOR loop 
may be executed zero times if the values of expl, exp2, and exp3 
dictate. 

Note that if the loop variable is an integer variable, expl, exp2 and 
the step exp are truncated to integers and all loop calculations are 
integer type. 

Example ; 

100 FOR A = 1 TO 10 STEP 3 
200 PRINT A 
300 NEXT A 
400 PRINT A 

Result: 

1 

4 

7 

10 

13 


VS BASIC Statements and Functions 11-53 



FORM Statement 



FORM performs the same function as FMT. 
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FS Function 






General Format: 
FS (file-exp) 


The FS function returns the file status for the most recent I/O 
operation on the specified file. The returned file status value is an 
alphanumeric value two characters long. FS can assume any of the 
following values: 

CONSEC. TAPE, and PRINTER File I/O 

'00' Successful I/O operation 

'10' End-of-file encountered 

'23' Invalid record number 

'30' Hardware error 

'34' No more room in the file 

'95' Invalid function or function sequence 

'97' Invalid record length 

INDEXED File I/O 

'00' Successful I/O operation 

'10' End-of-file encountered 

'21' Key out of sequence (WRITE statement in Output mode only) 

'22' Duplicate key 

'23' No record found matching specified key 

'24' Supplied key exceeds any key in the file (Input, I/O, or Shared 
mode) 

'30' Hardware error 

'34' No more room in the file (Output or I/O mode) 

'95' Invalid function or function sequence 
'97' Invalid record length 

SHARED Mode I/O Errors (not normally encountered by the VS BASIC user) 

'80' Invalid Key area (START, READ KEYED) 

•81' Invalid READ NODATA 

'82' Label update error 

'83' Sharing task was terminated 

'84' Invalid record size/record area 

(Record size > 2048) 

Syntax Example : 

100 Y$ = FS(#1) 
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GET Statement 




General Format: 


GET 


{ file-exp \ [ r 11 iQiMP / line number \ 

alpha-exp J statement label j 

[data /goto \ /linenumber \ 

,uMiM SgoSUBj I statement label J 


. arg [,arg]... 


where: 
arg = 


{ receiver 
array-designator 


GET allows you to extract data from the record area in a file or from 
an alpha expression USING the referenced Image (%) or FMT statement, 
or using standard format. Data in the record area referenced by the 
file expression is that read with the last READ statement. This data 
is available to GET until it is overwritten by another READ from the 
same file, or by a PUT, WRITE, or REWRITE for that file. 

The DATA exit is taken if data conversion fails (e.g., character 
string moved to numeric variable, alpha expression too short to fill 
all the arguments, etc.). 


Syntax Examples : 

100 GET #A USING 300,B,DATA GOTO 500 
300 FMT PIC{####) 

NOTE 


You can use GET to convert numeric data from internal formats used by 
COBOL programs to VS BASIC numeric data format. See Appendix C for 
information on numeric data compatibility between VS BASIC and COBOL. 




11-56 VS BASIC Statements and Functions 





GOSUB Statement 




General Format; 

r-nci ID /linenumber \ 
GOSUB I statement label J 


Use the GOSUB statement to transfer program execution to the first 
program line of a subroutine* (The use of the GOSUB statement is 
discussed in Section 6.4.1.) The program line can be any VS BASIC 
statement, including a REM statement or a statement label line. The 
logical end of the subroutine is a RETURN or RETURN CLEAR statement. 
A RETURN statement directs execution to the statement following the 
last executed GOSUB. A RETURN CLEAR statement clears the subroutine 
information but causes no branch. 

You can use the GOSUB statement to perform a subroutine v/ithin a 
subroutine; this technique is called "nesting" of subroutines. 

Do not enter subroutines repeatedly without executing a RETURN or 
RETURN CLEAR. Failure to execute a RETURN or RETURN CLEAR causes 
return information to accumulate in a table, which can eventually 
cause a memory stack overflow error. 

Example : 

120 X = 20:GOSUB 200:PRINT X 
125 

130 GOSUB TEST 


190 TEST: 

200 REM SUBROUTINE BEGINS 


210 RETURN:REM SUBROUTINE ENDS 
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GOSUB' Statement 


General Format; 
GOSUB'int[(arg[,arg]...)] 
where: 

0<=int<= 256 



The GOSUB' statement specifies a transfer to a marked subroutine 
rather than to a particular program line, as does the GOSUB 
statement. (Using the GOSUB' statement is discussed in Section 
6.4.2.) A subroutine is marked by a DEF FN' statement. When a GOSUB' 
statement is executed, program execution transfers to the DEF FN' 
statement having an integer identical to that of the GOSUB' statement 
(i.e., (30SUB'6 transfers execution to the DEF FN'6 statement). 
Subroutine execution continues until a subroutine RETURN or RETURN 
CLEAR statement is executed. The rules applying to GOSUB also apply 
to the GOSUB' statement. Unlike a normal GOSUB, however, a GOSUB' 
statement can contain arguments whose values can be passed to 
variables in the marked subroutine. 

The values of the expressions, literal strings, or alphanumeric 
variables are passed to the variables in the DEF FN' statement left to 
right. Elements of arrays must be explicitly referenced (i.e., they 
cannot be referenced by the array designator or array name alone). 

The arguments of the GOSUB' must be passed to variables of the same 
type (i.e., alpha expressions must be passed to alpha variables, and 
numeric expressions must be passed to numeric variables). 

Do not enter subroutines repeatedly without executing a RETURN or 
RETURN CLEAR. Failure to execute a RETURN or RETURN CLEAR causes 
return information to accumulate in a table, which can eventually 
cause a stack overflow error. 
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Examples : 


100 GOSUB'7 
150 END 

200 DEP FN'7:SELECT PRINTER (80) 
210 RETURN 


100 GOSUB'12 ("JOHN'M2.4,3*X + Y) 
200 END 

300 DEF FN'12{A$,B,C(2)) 

400 PRINT A$,B,C(2) 

500 RETURN 
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GOTO Statement 




General Format: 

rnm ) number 1 
‘I statement label J 


This statement transfers execution to the specified line number or 
statement label; execution continues at the specified line statement. 

Example : 

100 J = 25 
200 K = 15 
300 GOTO TEST 
400 Z = J+K+L+M 
500 PRINT Z,Z/4 
600 END 
650 TEST 
700 L = 80 
800 M = 16 
900 GOTO 400 

Output: 

136 34 
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HEX Function 




General Format: 

HEXIhhlhh]...) 

where: 

h = hexdigit {0 to 9 or A to F) 


The hexadecimal function, HEX, is a form of literal string that 
enables any 8-bit code to be used in a BASIC program. Each character 
in the literal string is represented by two hexadecimal digits. If 
the HEX function contains an odd number of hexdigits or if it contains 
any characters other than hexdigits, an error results. 

Syntax Examples : 

100 A$ = HEX{0C0A0A) 

200 IF A$ > HEX(7F) THEN 100 
300 PRINT HEX(8001);"TITLE" 

Output: TITLE 

(The HEX value of 8001 causes the text "TITLE" to be highlighted.) 
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HEXPACK Statement 


General Format: 



HEXPACK alpha-receiver FROM alpha-exp .DATA 

/goto \ 

|GOSUBJ 

1 line number /1 
statement label r I 


The HEXPACK statement converts an ASCII character string that 
represents a string of hexadecimal digits into the binary equivalent 
of those hexadecimal digits. Hexadecimal digits entered from the 
keyboard can be entered as ASCII characters; they can then be 
converted from ASCII code to their true binary equivalent with 
HEXPACK. For example, the hexadecimal digit A has a binary value of 
1010. However, this digit is represented by an ASCII character A, 
which has a binary value of 01000001. The HEXPACK statement can be 
used to convert the binary value of ASCII character A into the binary 
value of the hexadecimal digit A, and to store this value in the 
specified alpha receiver. 

The alpha expression (actual length) contains the ASCII character 
string that represents a string of hexadecimal digits. Each pair of 
ASCII characters is converted to one byte of the corresponding binary 
value. Only certain ASCII characters constitute legal representations 
of hexadecimal digits. These include the characters 0 through 9 and A 
through F, as well as the special characters <, =, >, and ?. 

These characters are converted to the following binary values; 


ASCII Character 

Binary Value 

0 

0000 

1 

0001 

2 

0010 

3 

0011 

4 

0100 

5 

0101 

6 

0110 

7 

0111 

8 

000 

9 

1001 

A or : 

1010 

B or ; 

1011 

C or < 

1100 

D or = 

1101 

E or > 

1110 

F or ? 

1111 
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If the alpha expression contains any characters other than those 
listed above, including embedded spaces (i.e., any character that is 
not a legal representation in ASCII of a hexadecimal digit), an error 
occurs; if the DATA exit is specified, it is taken. 

If the alpha expression contains an odd number of legal hexadecimal 
digits, it is padded on the right with one hex zero. 

The alpha receiver receives the converted binary value. Since each 
pair of characters in the value of the alpha expression is converted 
to a 1-byte binary value in the alpha receiver, the alpha receiver 
should have at least half as many bytes (defined length) as the alpha 
expression. If the alpha receiver is too short to contain the entire 
converted binary value, an error occurs and program execution halts. 
If the alpha receiver is longer than the converted binary value, the 
binary value is left-justified, and the remaining bytes of the alpha 
receiver are not modified. 

Example 1 : 

100 DIM P$2, U$4 

200 INPUT "VALUE TO BE PACKED",U$ 

300 HEXPACK P$ FROM U$ 

400 PRINT HEXOF (P$) 

Output: 

VALUE TO BE PACKED?12C9 
12C9 

The availability of the special characters ":" (HEX (3A)) through "?" 
(HEX (3F)) to represent hexadecimal digits A through F (1010 through 
1111) means that HEXPACK will recognize any ASCII code with a 
high-order 3 digit (hexadecimal 30 through hexadecimal 3F) as a 
legitimate representation of a hexadecimal digit. This fact makes it 
easy to transform any code into an acceptable representation of a 
hexadecimal digit, and to perform operations such as packing the 
low-order digits (low-order four bits) from a string of hexadecimal 
digits. The technique is illustrated in Example 2. 


Example 2: 


100 

DIM P$2, V$4 

200 

V$ = HEX (01020C09) 

300 

V$ = OR ALL (HEX(30)) 

400 

HEXPACK P$ FROM V$ 

500 

PRINT HEXOF(P$) 

(Xitput: 


12C9 
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Syntax Examples 


HEXPACK A$ FROM B$ 

HEXPACK STR(A$,1,3) FROM STR(B$,7) 
HEXPACK A$() PROM B$() 

HEXPACK A$ FROM "3AFC282C" 
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HEXPRINT Statement 


General Format: 



HFXPRINT /alpha variable \ 

ncArmiN i ^glpha array designator J 

N ' 1 / alpha variable H 

1 1 ' / designator j 1 

[;] 


This statement prints the value of the alpha variable or the values of 
the alpha array in hexadecimal notation. The printing or display is 
done on the device currently selected for PRINT operations (refer to 
SELECT in this section). The defined lengths of the alpha values are 
printed. Arrays are printed one element after another with no 
separation characters. A new line is started after the value{s) of 
each alpha variable (or array) in the argument list, unless the 
argument is followed by a semicolon. If the printed value of the 
argument exceeds one line on the workstation or printer, it continues 
on the next line or lines. Since the carriage width for PRINT 
operations can be set to any width by the SELECT statement, this can be 
used to format the output from long arguments. 

Note that HEXPRINT X$, Y$, Z$ is the same as PRINT HEXOF (X$), HEXOF 
(Y$), HEXOF (Z$). 

Syntax Example : 

100 HEXPRINT A$ 
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HEXUNPACK Statement 


General Format: 

HEXUNPACK alpha-exp TO alpha-receiver 




The HEXUNPACK statement converts the binary value of an alpha 
expression (defined length) to a string of ASCII characters 
representing the hexadecimal equivalent of that value. The resulting 
characters are stored in the alpha receiver. 

HEXUNPACK is the logical inverse of HEXPACK, except that characters 3A 
through 3F are not used. The characters produced are in the range 0 
through 9 and A through F. 

If the alpha receiver is not at least twice as long as the alpha 
expression (defined length), an error occurs. If it is longer, the 
result is left-justified and unused characters remain unchanged (as 
with HEXPACK). 

Example ; 


100 

DIM P$2, 

U$4 

200 

P$ = HEX 

(12C9) 

300 

HEXUNPACK P$ TO U$ 

400 

PRINT U$ 


Output: 



12C9 


Syntax Examples : 

HEXUNPACK A$ TO B$ 

HEXUNPACK STR(A$, 5) TO STR(B$, 1, 4) 
HEXUNPACK A$() TO B$() 
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IF...THEN...ELSE Statement 






General Format: 


where: 


f line number') 

pinenumber'j 

executable 1 

1 executable 1 

statement* V 

ELSE < statement* V 

statement 1 

1 statement I 

Uabel J 

Uabel ) . 


‘except another IF 


alpha exp operator alpha exp 
numeric exp operator numeric exp 


relation = \ 


{ AND 
OR 
XOR 


relation 


I NOT relation I 

I (relation) I 



The IF statement causes conditional transfer or statement execution. 

Depending on the value of the relation, execution continues as follows: 

1. If the relation is true : 

a. If "THEN line number (or statement label)" is specified, 
execution continues at the specified line number or statement 
label. 

b. If "THEN executable statement" is specified, the statement is 
executed. Program execution then continues at the next 
executable statement. 

c. In either case, the ELSE clause is ignored. 
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2. If the relation is false : 

a. If the ELSE clause is not specified, execution continues at the 
next executable statement. 

b. If the ELSE clause is specified, execution continues at the 
specified line number or statement label. Program execution 
then continues at the next executable statement. 

c. In either case, the THEN clause is ignored. 

Two expressions are compared using standard numerical order. Integers 
are converted to floating-point before being compared v/ith 
floating-point values. Two alpha expressions are compared using their 
ASCII hexadecimal codes, with the shorter expression right-padded v;ith 
blanks (HEX(20)). 

Complex IF statements containing character relation expressions of the 
form "IF A AMD B AMD C AND D THEM XYZ" can in some cases cause program 
checks or random branches. It is recommended that such complex 
relations be v/ritten in tv/o separate statements. 

The hierarchy of execution of the relational expression is as follows: 

1. Parentheses 

2 . <, <=, >, >=, <>, = 

3. MOT 

4. AND, OR, XOR 

5. Left-to-right execution 






NOTE 


Nested IF statements are not allowed. 


Syntax Examples : 

100 IF A > .5 THEN 1000 

200 IF A$>B$ AND B$>C$ THEN B = 5 ELSE B = 0 
300 IF NOT A = B THEN 1000 

400 IF E$ <= F$ AND (NOT N > I) THEN 1000 ELSE 800 
500 IF A > B THEN TEST ELSE NO TEST 
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Image (%) Statement 






General Format: 


% 


{ character string^ 
format spec j 


where: 

character string = 


{ any character 
except # 


format spec = 



[$]#...[,][#... [J]... [.][#... Kt 11!) 



The Image {%) statement is a nonexecutable statement that formats 
output from PRIWTUSING, disk I/O, and GET and PUT statements. One 
format specification is used for each numeric or alpha value, left to 
right. 

For alphanumeric values, the format specification is filled from left 
to right, regardless of the editing characters. The output value is 
right-padded with blanks or truncated to fit the format specification. 

For numeric values, the editing characters in the format specification 
are interpreted depending upon the value to be formatted. 

Format Characters 


Leading : 

+ '+' if > 0, if < 0 

blank if > 0, if < 0 
$ *$' precedes the number 

(The above three characters float to just before the leftmost nonzero 
digit location.) 

# Digit position — blank if leading zero. 

. Decimal point. 

, Comma if at least one significant digit is positioned to the 

immediate left; otherwise, blank. 
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TTTT exponent E+xx for exponential output. If present, the digit 

positions are filled with significant digits (no leading zeros) 
and the exponent is scaled accordingly. 

Trailing ; 

+ '+’if>0, '-’if<0 

- blank if > 0, if < 0 

++ 2 blanks if > 0, 'CR' if < 0 

— 2 blanks if > 0,'DB’ if < 0 


MOTES 


1. If a leading sign is present, the trailing sign is ignored. That 
is, it becomes part of the next character string. 

2. If no signs are present, the absolute value of the number is 
printed. 


1. There must be at least a single # in a format specification, and 
the output field width is always the same length as the format 
specification, whether the output is numeric or alphanumeric. 

2. For numeric output: 

a. Fractions are truncated. 

b. If the format is insufficient for the integer part of the 
number, the format specification itself is output, with the 
correct leading sign, if the leading sign character is present. 

3. If all format specifications are not used, everything up to the 
first unused format is used, including a final character string. 

4. A trailing character string in an Image {%) statement is 
considered to extend to the last nonblank character. 

5. Continuation characters are illegal in the format clause; the 
format clause is considered at an end if an exclamation point (!) 
is encountered. 

Syntax Examples : 

100 %FEAR IN A HANDFUL OF DUST +###,###,###.## 

100 ACCEPT A,B,C 

200 PRINTUSING 300, A,B,C 

300 %$##,###.##++ ###.###-###.##?TIT 

400 STOP 
500 GOTO 100 
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INIT Statement 


General Format: 

INIT (alpha-exp) alpha-receiver [.alpha-receiver]... 


The INIT statement initializes the specified alphanumeric receivers. 
Each character in the defined length of the alpha receiver(s) is set 
equal to the first character of the alpha expression. For arrays, 
each character of each element of the array is set to the first 
character of the alpha expression. 

Example ; 

100 DIM A$5, M$<5)3 
200 INITC'?") A$, M$() 


Result: 


A$ 

= 

ii9999«7n 

M$(l) 

= 

II 9 9 9 11 

M$(2> 

= 

11 999 II 

M$(3) 

= 

11 999 H 

M$(4) 

= 

II 99 9 II 

M$(5) 

= 

♦199911 
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INPUT Statement 


General Format: 

INPUT [literal,] receiver Lreceiver]... 


This statement allows you to supply data during the execution of a 
program. If you want to supply the values for A and B while running 
the program, a statement such as 

400 INPUT A,B 
or 

400 INPUT "VALUE OF A,B",A,B 

must be entered before the first program line that requires either of 
these values (A,B). When the system encounters this INPUT statement, 
it prints the message VALUE OF A,B, followed by a question mark (?), 
and waits for you to supply the two numbers. Once the values are 
supplied, program execution continues. The program assigns values 
left to right, one at a time. The v/orkstation is used for entering 
data. 


NOTE 


When the compiler option MINANS = YES is selected, there must be as 
many INPUT values as there are INPUT receivers or an error is 
generated and additional input is required. The null input 
specification is not acceptable. If for any reason the entire 

INPUT line cannot be processed (an error is generated with the prompt 
to respecify), none of the INPUT assignments are made. 


Enter each value in the order in which it is listed in the INPUT 
statement. The values entered must be compatible with receivers in 
the INPUT statement. If several values are entered, they must be 
separated by commas or entered on separate lines. Use as many lines 
as necessary to enter the required INPUT data, but the compiler option 
MINANS = NO must be selected. When MINANS = YES is selected, multiple 
lines are not allowed. To include commas or leading blanks as part of 
an alpha value, enclose the value in double or single quotes (" or '), 
for example, "BOSTON, MASS.". 
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Variables in the INPUT list that you do not want to change can be 
skipped over by entering a null value, i.e., a comma not immediately 
preceded by a data item. (However, null values are not allowed if the 
compiler option MINANS = YES is selected.) For example. 

Program: VALUE OF A,B,C,D? 

Your input: 4.3,2.0,,3.5 

Result: Variable C will not be changed; A, B, and D get new values. 

You can terminate an input sequence without supplying any additional 
input values by simply keying ENTER with no other information 
preceding it on the line. This is true only when the compiler option 
MINANS = NO is selected, and causes the program to immediately proceed 
to the next program statement. The INPUT list receivers that have not 
received values remain unchanged. 

When entering alphanumeric data, literal strings need not be enclosed 
in quotes. However, leading blanks are ignored and commas act as 
string terminators. (This also applies to subroutine parameters; 
refer to Sections 3.4.1 and 6.5.5) 


Example 1 : 


100 INPUT X 


Output: 

7 12.2 (ENTER) 

(underlined portion supplied by you) 


Example 2 : 

200 INPUT "MORE INFORMATION",A$ 
300 IF A$ = "NO" THEN END 
400 INPUT "ADDRESS",B$ 

500 GOTO 200 


Output: 

MORE INFORMATION? YK (ENTER) 
ADDRESS? BOSTON, MASS (ENTER) 
MORE INFORMATION? ^ (ENTER) 
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Program Fimction Keys in Input Mode 


You can use PF keys in conjunction with INPUT. If a PP key is defined 
for text entry (refer to DBF FN') and an INPUT statement is executed, 
pressing the PF key causes the character string in the DBF FN' 
statement to be displayed on the CRT. The displayed value is stored 
in the variable that occurs in the INPUT statement when the BNTBR key 
is pressed. For example, 

100 DBF FN'01"COLOR T.V." 

200 INPUT A$ 

Result: 

0 

(Now, pressing PFl causes "COLOR T.V." to appear on the CRT.) 

7COLOR T.V._ 

(CRT Cursor) 

If the PF key is defined to call a marked subroutine (refer to 
DBF FN') and the system is awaiting input, pressing the PF key causes 
the specified subroutine to be executed. No assignment occurs, and 
the values entered before pressing the PF key are ignored, unless the 
subroutine has an argument list. If so, as many values as are 
required are taken, starting from the leftmost value keyed; those left 
over are ignored. 

The workstation alarm sounds if there are too few values or if those 
values do not correspond correctly to the receivers in the GOSUB' 
argument list. An illegal PF key also causes an alarm. When the 
RBTURN statement is encountered, control returns to the INPUT 
statement and the INPUT statement is executed again. Do not enter 
subroutines repeatedly through PF keys unless a RETURN or RETURN CLEAR 
statement is executed. Otherwise, return information accumulates in a 
table and can eventually cause a stack overflow error. 
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This program example enters and stores a series of numbers. When PF2 
is pressed, they are totalled and printed. 





100 DIM A(30) 

200 N = 1 

300 INPUT "AMOUNT",A(N) 
400 N = N+1;G0T0 300 
500 DEFFN'02 
600 T = 0 

700 FOR I = 1 TO N 
800 T = T+A(I) 

900 NEXT I 

1000 PRINT "TOTAL =" ;T 
1100 N = 1 
1200 RETURN 

Output: 

AMOUNT? 7 (ENTER) 
AMOUNT? 5 (ENTER) 
AMOUNT? 11 (ENTER) 
AMOUNT? (Press PF2) 
TOTAL =23 
AMOUNT? 
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INT Function 


General Format: 
INTinumeric exp) 


The INT (integer) function returns an integer value that is the 
greatest integer less than or equal to the value of the numeric 
expression specified as the argimient. 

Numeric Examples ; 

INT( 1.5) = 1 

INT(-1.5) = -2 

Syntax Example : 

100 Y% = INT(4.5) 
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KEY Fiinction 




General Format: 
KEY(file-exp (,exp]) 


KEY returns the primary key (or an alternate key) of the last record 
read from the specified file. If exp is 0 or omitted, the primary key 
is returned. Otherwise, the alternate key with key number = exp (from 
SELECT) is returned. (This is for alternate indexed files only.) 

The length of the result is the (primary or alternate) key length as 
specified in SELECT. 

You can also use KEY as a receiver to set the (primary or alternate) 
key field in the record prior to WRITE or REWRITE. 

Syntax Example : 

100 Y = KEY(#1) 
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LEN Function 


General Format: 
LEN (alpha-exp) 


LEN determines the actual length, in bytes, of the alpha-expression. 

It can be used wherever a numeric expression is permitted. The result 
of LEN is an integer value. 

Example 1 ; 

100 A$ = "ABCD" 

200 PRINT LEN {A$) 

These program lines print the value 4 at execution time. 

Example 2 : 


300 X = LEN(A$) + 2 

Combined with lines 100 and 200 in Example 1, this line assigns the 
value 6 to X at execution time. 


Example 3 : 




100 A$ = "ABCD" 

200 PRINT LEN(STR(A$,2)) 

These lines give the value 15 at execution time. Since A$ is not 
explicitly dimensioned, the default value for its length is 16 bytes. 
The STR function extracts the bytes from A$, starting from the second 
byte, to its end. The length of such a value is 15. 

Example: 4 

100 A$ = "ABCD " 

200 PRINT LEN (A$), PRINT LEN(STR(A$,2)) 

When the compiler option MINANS = YES is selected, the default value 
for nondimensioned alpha expressions is 18. Blanks are considered 
significant. This code example produces the following output: 

when MINANS = NO 

4 15 

when MINANS = YES 
6 17 
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Example 5 ; 


100 DIM A$64 
200 A$ = "ABCD" 

300 PRINT LEN(STR(A$,POS<A$ = HEX(20)>)) 

These lines give the value 60 at execution time. The length of 
alpha scalar is initially 64. The value of the POS function is 
determined, giving the position of the first blank character in 
equal to 5. The STR function then extracts the number of bytes 
the first blank character to the end of the scalar. 
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LET Statement 




General Format: 

[LET] numeric variable [.numeric variable]... = numeric exp 
or 

[LET] alpha-receiver [.alpha-receiver]... = alpha-exp 
or 

[LET] alpha-receiver = logical exp 


The LET statement evaluates the expression following the equal sign 
and assigns the result to the receiver(s) specified preceding the 
equal sign. If more than one receiver appears before the equal sign, 
they must be separated by commas. If the right-hand side of the 
statement is a logical expression (refer to Section 5.7), only one 
receiver can appear on the left. 

An error results if a numeric value is assigned to an alphanumeric 
receiver, or if an alphanumeric value is assigned to a numeric 
variable. 

Examples ; 

400 LET X(3),Z,Y = P + 15 / 2 + SIN(P - 2.0) 

500 LET J = 3 

In the following example, LET is assvimed. 

100X=A*E-Z*Y 
200 A$ = B$ 

300 C$,D$(2) = "ABODE" 

The following routine produces the indicated output at execution time: 

100 C$ = ’ABODE’ 

200 A$ = "123456" 

300 D$ = STR(A$,2) 

400 E$ = HEX{41) 

500 PRINT A$,0$,D$,E$ 

Output: 

123456 ABODE 23456 A 
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The execution of 


[LET] red, rec2,..,, recn = value 
is equivalent to 

[LET] recn = value 
[LET] recn-1 = value 

.LET] reel = value 

for both alpha and numeric assignment. Assignment is right to left . 

MOTE _ 

When the compiler option MINAMS=YES is selected, an alpha expression 
larger than an alpha variable produces a fatal error. 
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LGT Function 


General Format: 
LGT(numeric exp) 




The LGT function returns a floating-point value equal to the common 
(base 10) logarithm of the numeric expression specified as the 
argument. 

Syntax Example : 

100 X = LGT(IOO) 

Numeric Example : 

LGT (100) = 2 
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LOG Function 


^ _ 

General Format; 
LOG (numeric exp) 


The LOG function returns a floating-point value equal to the natural 
logarithm (base "e") of the argument. LOG is the inverse function of 
EXP. 

Syntax Example : 

100 X = L0G(2) 

Numeric Example : 

LOG (10) = 2.30258509299404 
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MASK Function 




General Format: 
MASK (file-exp) 


MASK returns the alternate key access mask (alternate indexed file) 
for the last record read from the specified file. The result is a 
2-byte (16-bit) alphanumeric value whose bits (left to right) 
correspond to available alternate keys (1 through 16). Bits that are 
"on" (binary 1) specify that the record can be accessed, through a 
READ statement v/ith a key clause, by those alternate key paths. 

You can also use the MASK function as a receiver to set the alternate 
key mask for a record prior to a WRITE or REWRITE statement. 

Syntax Examples : 

100 A$ = MASK(#1) 

200 MASK(#2) = HEX(FFOO) 
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MAT + (MAT Addition) Statement 


General Format; 

MAT c = a + b 
where: 

c, a, and b are numeric array names 


This statement adds two matrices or vectors of the same dimension. 

The sum is stored in array c. Any two or all of a, b, and c may be 
the same array. Array c is implicitly redimensioned to have the same 
dimensions as arrays a and b. 

An error occurs and execution is terminated if the dimensions of a and 
b are not the same. 

Example 1 : 

100 DIM A(5,5),D(5,5),E(7),F(5),G(5) 

200 MAT A = A + D 
300 MAT E = F + G 
400 MAT A = A + A 

Example 2 : 

This program adds the corresponding elements of the three-by-three 
arrays D and E, to give the new array F. Array F is automatically 
redimensioned as a three-by-three array. 

100 DIM D(3,3),E(3,3),F(5,2) 

200 PRINT "ENTER ELEMENTS OF ARRAY D" 

300 MAT INPUT D 

400 PRINT "ENTER ELEMENTS OF ARRAY E" 

500 MAT INPUT E 
600 MAT F = D + E 
700 PRINT "ELEMENTS 
800 MAT PRINT F; 

a 1 

'1 1 

'2 2 

program is 

OF ARRAY F 

4 4 

4 4 

5 5 




Let D = 


When the 
ELEMENTS 

4 

4 

5 


OF ARRAY F":PRINT 


E = 


executed, array F is displayed: 
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MAT ASORT/DSORT Statement 




General Format: 


^ _ / numeric array namel 1 
S alpha array namel | 

_ f ASORT^^J (numeric array name2)\ 

^DSORT (alpha array name2) r 


Array 2 is 

sorted in ascending 

(ASORT) or descending (DSORT) order 

into array 
follows: 

1. Array 1 is redimensioned to correspond to array 2 as 

Array 2 

Array 1 

Redimensioned to 

(nxm)[L] 

(pxq)[k] 

(nxm)[L] 

(nxm)[L] 

(p)[k] 

(nmxl)[L] 

(n)[L] 

(pxq)[k] 

(nxl)[L] 

(n)[L] 

(p)[k] 

(nxl)[L] 


where n,p = 
m,q = 


number of rows; 
number of columns. 


An error occurs if array 1 is not as large (in bytes) as array 2. 


The sorted values are placed in array 1 row by row, starting with the 
first array variable. If array 1 is larger than array 2, the 
remaining locations are unchanged. 


As sorting is done directly into array 1, the two arrays cannot be the 
same (i.e., sort-in-place is not supported). 




NOTE 


Alphanumeric sorting uses the usual ASCII collating sequence. 


Syntax Examples ; 

100 MAT A = ASORT(B) 
200 MAT A$ = DSORT(B$) 
300 MAT C$ = AS0RT(B$) 




11-86 VS BASIC Statements and Functions 




Program Example : 


100 DIM A{3,4),B(2,3),C(7) 
200 MAT READ{B) 

300 MAT A = ASORT{B) 

400 MAT C = DSORT{B) 

500 MAT PRINT B,A^C 
600 DATA 3,4,7,1,5,2 

Result: 

B = 3 4 7 
15 2 

A = 1 2 3 

4 5 7 

7 

5 

C = 4 
3 
2 
1 
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MAT CON (MAT Constant) Statement 




General Format: 

MATc=CON I(d1[,d2])] 
where: 

c = numeric array name 

dl,d2 = expressions specifying new dimensions 
1<=d1,d2<=32767 


The MAT CON statement sets all elements of the specified array to 1 
Using (dl,d2) causes the matrix to be redimensioned. If (dl,d2) is 
not used, the matrix dimensions are as specified in a previous COM, 
DIM, or MAT statement, or are the default values. 


Syntax Examples : 

100 MAT A = CON(IO) 

200 MAT C = CON(5,7) 
300 MAT B = C0N(5*Q,S) 
400 MAT A = CON 

Program Example : 

100 MAT A = CON(2,2) 
200 MAT PRINT A; 




When this program is executed, the CRT displays the result in packed 
format: 


1 1 
1 1 
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MAT= (MAT Assignment) Statement 




General Format: 

MAT a=b 
where: 

a and b are both numeric or both alphanumeric array names 


The MAT= statement replaces each element of array a with the 
corresponding element of array b. Array a is implicitly redimensioned 
to conform to the dimensions of array b. 

Syntax Examples: 

100 DIM A(3,5),B{3,5) 

200 MAT A = B 

300 DIM C(4,6),D{2,4) 

400 MAT C = D 
500 DIM E(6),F(7) 

600 MAT F = E 

Program Example ; 


8 7 

5 4 

111 

Program; 

100 DIM A(3,3),B(2,3) 

200 MAT A = CON 
300 MAT PRINT A 
400 MAT INPUT B 
500 MAT A = B 
600 MAT PRINT A 


Let A = 1 


9 

B = 6 


Executing this program displays the constant three-by-three array A as; 

111 

111 

111 


in zoned format; the array B is input through the keyboard, and the 
new array A is displayed as follows in zoned format: 


9 8 7 

6 5 4 
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MAT IDN (MAT Identity) Statement 


General Format: 

MAT c = IDN [(d1,d2)] 
where: 

c = numeric array name 

d1,d2 = expressions specifying new dimensions 
1<=d1,d2<=32767 


The MAT IDN statement causes the specified matrix to assume the form 
of the identity matrix. If the specified matrix is not a square 
matrix, an error occurs and execution is terminated. 

Using (dl,d2) causes the matrix to be redimensioned. If {dl,d2) is 
not used, the matrix has the dimensions specified in a previous COM, 
DIM, or MAT statement. 

Syntax Examples ; 

100 MAT A = IDN{4,4) 

200 MAT B = IDN 

300 MAT C = IDN<X,Y) 

Program Example : 

100 DIM A{4,4) 

200 MAT A = IDN 
300 MAT PRINT A 

Executing this program displays matrix A in zoned format as: 

10 0 0 
0 10 0 

0 0 10 

0 0 0 1 
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MAT INPUT Statement 


General Format: 


MAT INPUT [literal.] 


( numeric array name [(d1 [,d2])] 1 r i 

y alpha array name [(d1 [,d2])[length]] j ' ' 


where: 

d = expression specifying a new dimension 
1 <=d1.d2<=32767 


length = expression specifying maximum length of each alpha array element 
1 < =length< =256 


The MAT INPUT statement allows you to supply values from the keyboard 

for an array during the running of a program. The MAT INPUT statement 

displays the literal, if given, and a question mark (?), and waits for 
you to supply values for the specified arrays. The dimensions of the 
array(s) are as last specified in the program (by a COM, DIM, or MAT 
statement), unless you redimension the array(s) by specifying the new 
dimension(s) after the array naine(s). The maximum length for 
alphanumeric array elements can be specified by including the length 
after the dimensions specification. If no length is specified, a 
default value of 16 is assumed. 

The values entered are assigned to an array row by row until the array 

is filled. If more than one value is entered on a line, the values 

must be separated by commas. Alphanumeric data with leading spaces or 
commas can be entered by entering quotation marks before and after the 
data value. A value surroxinded by single quotation marks (') is 
converted to lowercase; values enclosed in double quotation marks (") 
remain in uppercase. Refer to Section 3.4.1 for more information on 
the effect of quotation marks on alphanumeric values. 

Several lines can be used to enter the required data (unless the 
compiler option MINANS = YES is selected, which relults in a limit of 
a single line). Excess data is ignored. If there is a 
system-detected error in the entered data, the data must be re-entered 
beginning with the erroneous value. The data preceding the error is 
used as previously entered. Input data must be compatible with the 
array (i.e., numeric data for numeric arrays, alphanumeric literal 
strings for alphanumeric arrays). Entering no data on an input line 
(i.e., only keying ENTER to enter a carriage return) causes the 
remaining elements of the array currently being filled to be ignored. 
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The preceding rules apply to the MAT INPUT statement when the compiler 
options MINANS = NO is selected. There must be as many INPUT values 
as there are INPUT receivers or an error is generated and additional 
input is required. The null input specification is 

acceptable. If for any reason the entire INPUT line cannot be 
processed (i.e., an error is generated with the prompt to respecify), 
none of the INPUT assignments are made. A default value of 18 is 
assigned nondimensioned strings. 

Example with numeric variables : 

100 DIM A(2),B(3),C(3,4) 

200 MAT INPUT A,B(2),C(2,4) 

When this program is run, enter the values, separated by commas: 

-3, -5, .612, .41 

Press the ENTER key to enter these values for array elements A(l), 
A(2), B(l) and B(2). Enter the values 

-6.4, -5.6, 98 

separated by commas. Press ENTER to enter these values for the array 
elements C{1,1), C(l,2), and C(l,3). Press the ENTER key without 
entering further values to enter a carriage return and ignore the rest 
of the possible values for array C. 

Example with alphanumeric string variables : 

100 DIM C$(2),A$(4)4,B{3) 

200 MAT INPUT A${4)3,B(2),C$ 

Enter RAD, DEG, MIN, SEC, 2.5, 5.6, LAST RESULT, "ROTATE X,Y", and 
press ENTER. 

Result: 

RAD 

A$ = DEG 
B = 2.5 

C$ = LAST RESULT 
MIN 
5.6 

ROTATE X,Y 

SEC 
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MAT INV (MAT Inverse) Statement 


General Format: 

MATc = INV(a)Ld] 
where: 

c and a = numeric array names 

d = numeric variable; the value of the determinant of the array a 


The MAT IWV statement causes the inverse of matrix a to be placed in 
matrix c. Matrix c is redimensioned to have the same dimensions as 
matrix a. Matrix a must be a square matrix; matrix c must be a 
floating-point matrix. If matrix a is singular (i.e., cannot be 
inverted) and d is specified, then d equals zero after MAT INV is 
encountered. If d is not specified, an error occurs. In either case, 
c is destroyed. A matrix can be replaced with the inverse of itself. 

After inversion, the variable d (if specified) equals the value of the 
determinant of matrix a. 

This statement uses the Gauss-Jordan Elimination Method done in 
place. As with any matrix inversion technique, results can be 
inaccurate if the determinant (or normalized determinant) of the 
matrix is close to zero. It is good practice to check the determinant 
after any inversion. 

The Gauss-Jordan Elimination Method also works best when values on the 
main diagonal are in the same range as other values in the matrix. In 
particular, avoid numbers with large negative exponents on the main 
diagonal when other values are not in this range. When in doubt, 
check the data before inversion and adjust or rearrange it accordingly 
(for example, zero elements that are close to zero, or rearrange data 
so that elements on the main diagonal are as large as possible). 

Syntax Examples ; 

100 MAT A = INV(B) 

200 MAT Z1 = INV(P),X2 
300 MAT F = INV(C),J3 
400 MAT C = INV(C) 
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The following program takes the four-by-four matrix A from the 
keyboard input, calculates its inverse, and prints both the result and 
the value of the determinant of A. 




100 DIM A(4,4) 

200 PRINT "ENTER ELEMENTS OF A 4x4 MATRIX" 

300 MAT INPUT A 
400 MAT B = INV(A),D 
500 MAT PRINT B 

600 REM B IS THE INVERSE OF A, D IS THE DETERMINANT OF A 
700 PRINT "VALUE OF DET.A = ";D 


If array A= 0 2 

0 0 
1 0 
4 8 


4 

1 

0 

16 


8 then array B= -1 0 

0 -3.5-2 

1 0 1 

32 10 


0 

-4 

0 

1 


.25 

1 

0 

-.25 


and the value of the determinant of A = -8. 
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MAT * (MAT Multiplication) Statement 




General Format; 

MAT c=a*b 
where: 

c, a, and b are numeric array names 


The MAT * statement causes the product of arrays a and b to be stored 
in array c. Array c cannot appear on both sides of the equation but a 
and b can be identical. If the number of columns in matrix a does not 
equal the number of rov/s in matrix b, an error occurs and execution is 
terminated. The resulting dimension of c is determined by the number 
of rows in a and the number of columns in b. 

Syntax Example : 

100 DIM A(5,2),B(2,3),C{4,7) 

200 DIM E(3,4),F(4,7),G{3,7) 

300 MAT G = E * F 
400 MAT C = A * B 

Program Example : 

100 DIM A{2,3),B(3,4) 

200 MAT INPUT A,B 
300 MAT C = A * B 
400 MAT PRINT C 


LetA=0 1 4,B=5 1 0 4 

7 7 7 4 1 0 4 

3 4 3 4 


When the program is executed and arrays A and B are entered, array C 
is displayed as: 

16 17 12 20 

84 42 21 84 
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MAT PRINT Statement 




General Format: 



MAT PRINT array name < 

^ array name 

1{)1 


The MAT PRINT statement prints arrays in the order given in the 
statement. Each matrix is printed row by row. All elements of a row 
are printed on as many lines as required. A multiple MAT PRINT is 
treated like several single MAT PRINTs. Numeric arrays are printed in 
zoned format unless the array name is followed by a semicolon, in 
which case the array is printed in packed format. For alphanumeric 
arrays, the zone length is set equal to the maximum length defined for 
each array element (not always the default). A vector (a 
one-dimensional array) is printed as a column vector. 

Syntax Examples : 

100 DIM A(4),B{2,4),B$(10),C$(6) 

200 MAT PRINT A;B,C$ 

300 MAT PRINT A,B$ 

Program Example : 

This program takes nine alphanumeric quantities as input, each up to 
16 characters long, and prints them as a three-by-three array in 
packed format. 

100 DIM Z$(3,3) 

200 MAT INPUT Z$ 

300 MAT PRINT Z$; 

Enter the values: 

A, B, C, D, E, F, G, H, I 

Results: 

ABC 

DEF 

GHI 
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MAT READ Statement 


General Format: 

MAT READ /numeric array name! /(d1[.d2]) \\ [,..l 

^alpha array name j M (dl [,d2])[length]/ 1 [ J 

where: 

d = expression specifying a new dimension 
1<=d1.d2<=32767 


length = expression specifying maximum length of each alpha array element 
1 < =length< =256 


Use the MAT READ statement to assign values contained in DATA 
statements to array variables without referencing each member of the 
array individually. The MAT READ statement causes the referenced 
arrays to be filled sequentially with the values available from the 
DATA statement(s). Each array is filled row by row. Values are 
retrieved from a DATA statement in the order in which they occur on 
that program line. If a MAT READ statement references beyond the 
limit of existing values in a DATA statement, the next sequential DATA 
statement is used. If the program contains no more DATA statements, 
an error occurs and execution is terminated. 

Alphanumeric string arrays can also be used in the list. The 
information entered in the DATA statement must be compatible with the 
array (i.e., numeric values for numeric arrays, alphanumeric literals 
for alphanumeric arrays). 

The dimensions of the array(s) are as last specified in the program 
(by a COM, DIM, or MAT statement), unless you redimension the array(s) 
by specifying new dimension{s) after the array name(s) in the MAT READ 
statement. The maximum length for alphanumeric array elements can be 
specified by including the length after the dimension specification. 
When no length is specified, a default of 16 is used when the compiler 
option MINANS = NO is selected and 18 when MINANS = YES. 

Program Example ; 

100 DIM A{1),B(3,3) 

200 MAT READ A,B(2,3) 

300 DATA 1, -.2,315, -.398, 6.21, 0, 0 
400 MAT PRINT A,B 

Result: 

A = 1 B = -.2 315 -.398 

6.21 0 0 


VS BASIC Statements and Functions 11-97 




MAT REDIM Statement 


General Format: 

MAT REDIM redim-eltLredim-elt]... 
where; 

roHirr, - i numcric array name (exp1 l,exp2]) \ 
~ S alpha array name (expl Lexp2j)lexp3] j 

1 < = exp1 < 32767 
1 < = exp2 < 32767 
1 < = exp3 < 256 


The MAT REDIM statement redimensions the specified arrays to the 
dimensions specified by the expressions. The rules for MAT REDIM 
statements are the same as those for DIM statements, except as follows: 

1. As indicated, alpha scalars cannot be redimensioned. 

2. MAT REDIM can occur anywhere in the program or subprogram. Its 
only effect is to change the dimensions and lengths of the 
specified array. It does not affect the values currently assigned 
to array elements. 

3. The total (byte) space required for the array must be no greater 
than that initially allotted to it by DIM or default (10 by 10, 
length = 16 when MINANS = NO and 18 when MINANS = YES, for alpha 
arrays). 

4. If exp3 is omitted, it is set to 16, regardless of the previous 
length. 

5. A matrix cannot be redimensioned as a vector, or vice versa. 

Syntax Examples : 

100 MAT REDIM A(10),B$(10,20)10 
200 MAT REDIM A{20,30) 
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MAT()* (MAT Scalar Multiplication) Statement 




General Format: 

MAT c = (k) * a 
where: 

c and a are numeric array names and k is an expression 


With the MAT()* statement, each element of array a is multiplied by 
the value of expression k. The product is stored in array c. Array c 
can appear on both sides of the equation. Array c is redimensioned to 
the same dimensions as array a. 

Syntax Examples : 

100 MAT C = (SIN(X))*A 
200 MAT D = {X+Y*2)*A 
300 MAT A = (5>*A 




Program Example : 


This program allows you to enter a three-by-three array and a scalar. 
It then performs scalar multiplication and displays the result. 


100 PRINT "ENTER DATA FOR A 3x3 ARRAY" 

200 MAT INPUT C(3,3) 

300 PRINT "ENTER SCALAR" 

400 INPUT K 
500 MAT A = (K>*C 
600 MAT PRINT A; 

5 

10 
5 


LetC=5 3 1 ,K=5 then A = 25 15 

2 2 2 10 10 
111 55 
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MAT - (MAT Subtraction) Statement 




General Format: 

MAT c = a - b 
where: 

a, b. and c are numeric array names 


The MAT - statement subtracts numeric arrays of the same dimension. 

The difference of each pair of elements is stored in the corresponding 
element of c. Any two or all of a, b, and c can be the same. An 
error occurs and execution is terminated if the dimensions of a and b 
are not the same. Array c is redimensioned to have the same 
dimensions as arrays a and b. 

Syntax Example : 


100 DIM A{6,3),B{6,3),C(6,3),D(4),E(4) 

200 MAT C = A - B 
300 MAT C = A - C 
400 MAT D = D - E 

Program Example ; 

100 DIM D(3,3), E(3,3) 

200 MAT INPUT D 
300 MAT INPUT E 
400 MAT F = D - E 
500 MAT PRINT F 

-2 
-2 
-1 


If D = 1 
1 
2 


E = 3 
3 
3 


3, then F = -2 -2 


-2 -2 

-1 -1 
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MAT TRN (Transpose) Statement 




General Format: 

MAT c = TRN (a) 
where: 

a and c are array names (both numeric or both alphanumeric) 


The MAT TRN statement causes array c to be replaced by the transpose 
of array a. Array c is redimensioned to the same dimensions as the 
transpose of array a. Array c cannot appear on both sides of the 
equation. 

Syntax Example : 

100 MAT C = TRN(A) 

Program Example : 

100 DIM A(3,3) 

200 MAT INPUT A 
300 MAT C = TRN(A) 

400 MAT PRINT C 

Let A = 9 8 7 

6 5 4 

3 2 1 

When the program is executed, C is displayed as: 

9 6 3 

8 5 2 

7 4 1 
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MAT ZER (MAT Zero) Statement 


General Format: 

MATc = ZERl(d1[,d2])] 
where: 

c = numeric array name 

d1 ,d2 = expressions specifying new dimensions 
1 < = d1,d2 <=32767 


The MAT ZER statement sets all elements of the specified array equal 
to zero. Using (dl,d2) causes the matrix to be redimensioned. If 
(dl,d2) is not used, the matrix retains the dimensions specified in a 
previous COM, DIM, or MAT statement. 

Syntax Examples ; 

100 MAT C = ZER{5,2) 

200 MAT B = ZER 

300 MAT A = ZER(F,T+2) 

400 MAT D = ZER(20) 
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Mathematical Functions 


General Form 1 applies to most mathematical functions. General Forms 
2 through 4 follow the discussion of General Form 1. 


General Format 1: 


function (exp) 


where: 


function = 


' SIN 
COS 
TAN 
ARCSIN 
ARCCOS 
ARCTAN 


; ATN 
^ ABS 
EXP 
INT 
LGT 
LOG 
SGN 
SQR 






Trigonometric Functions 

The sine, cosine, tangent, arcsine, arccosine, and arctangent 
functions are available in VS BASIC. You can easily specify other 
trigonometric functions by using these functions in expressions. 
(When using these functions in combination, be careful to avoid 
significant data conversion errors. Refer to Section 4.4.1 for a 
complete discussion.) 


Function Name 

Sample Expression 

Meaning 

SIN 

SIN(X) 

The sine of the argument 

COS 

COS(X) 

The cosine of the argument 

TAN 

TAN(X) 

The tangent of the argument 

ARCSIN 

ARCSIN{X) 

The inverse sine of the argument 

ARCCOS 

ARCCOS(X) 

The inverse cosine of the argument 

ARCTAN 

ARCTAN(X) 

The inverse tangent of the argument 

ATN 

ATN(X) 

Synonym for ARCTAN 
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other Nuroerical Functions 


The following table describes the remaining numerical functions (refer 
to Section 4.4.1): 


Function Name 

Sample Expression 

Meaning 

ABS 

ABS(X) 

The absolute value of the 
argument: -X if X < 0; 

X if X > = 0, 

SQR 

SQR{X) 

The square root of the 
argument; X raised to 
the .5 power. 

EXP 

EXP(X) 

The exponential function; 

"e" (2.718...) raised to 
the Xth power. 

INT 

INT(X) 

The greatest-integer 
function; the greatest 
integer less than or 
equal to the argument. 

LGT 

LGT(X) 

Common (base 10) 
logarithm. 

LOG 

LOG(X) 

Natural (base "e") 
logarithm; inverse 
function of EXP. 

SGN 

SGN(X) 

The signuro function; 

-1 if the argument is 
negative; 0 if the 
argument is zero; 

+1 if the argument is 
positive. 
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Mathematical Functions (Continued) 




General Format 2: 
function (exp[,exp]...) 

where: 
function = 



Function Name Sample Expression Meaning 

MAX MAX(X,Y,Z) The value of the largest 

element in the argument 
list. 

MIN MIN(X,Y,Z) The value of the smallest 

element in the argument 
list. 


Refer to Section 4.4. 
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Mathematical Functions (Continued) 




General Format 3: 
MOD(exp,exp) 


Function Marne Sample Expression Meaning 

MOD MOD(X,Y) The modulus function; 

the remainder of the 
division of the first 
element by the second 

Refer to Section 4.4. 
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Mathematical Functions (Continued) 





3.14159265358979323. 


Refer to Section 4.4 for more information on numeric functions. 
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MAX Function 




General Format: 

MAX (exp [,exp]...) 
where: 

exp = a numeric scalar or numeric array 


The MAX function returns the largest element in the argument list, or, 
in the case of an array, the largest element in the array. 

Syntax Examples ; 

100 A = MAX{B,C,D) 

200 D = MAX(E()) 

Numeric Examples : 

MAX(4,3,2,1) = 4 
MAX(10,100,1000) = 1000 






11-108 VS BASIC Statements and Functions 




MIN Function 




General Format: 

MIN(exp[,exp]...} 
where: 

exp = a numeric scalar or numeric array 


The MIN function returns the smallest element in the argument list or 
array. 

Syntax Examples : 

100 MIN {B,C,D) 

200 MIN (EO) 

Numeric Examples : 

MIN(4,3,2,1> = 1 
MIN{10,100,1000) = 10 
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MOD Function 


General Format: 

MOD (numeric exp, numeric exp) 


The MOD (modulus) function returns a numeric value equal to the 
remainder of the division of the first expression by the second. The 
value returned is an integer value if both expressions are integers; 
otherwise, it is floating-point. 

Syntax Example ; 

100 Y = MOD(7,4) 

Numeric Example : 

MOD(5,3) = 2 
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NEXT Statement 


General Format: 

NEXT numeric scalar variable [.numeric scalar variable]... 


The NEXT statement defines the end of a FOR...NEXT loop. It must 
contain the same index variable(s) as a previously executed FOR 
statement. A multiple NEXT is executed left to right. For example, 

NEXT I,J,K 

is equivalent to 

NEXT I 
NEXT J 
NEXT K 

When the compiler option MINANS = NO is selected and a FOR...NEXT loop 
is encountered, the index variable takes the value initially assigned 
in the FOR statement. When the NEXT statement is executed, the STEP 
value specified in the FOR statement is added to the value of the 
index. (If no STEP value is given, +1 is used.> If the result is 
within the range specified in the FOR statement, the result (index + 
STEP) is assigned to the index variable and execution continues at the 
statement following the FOR statement. If the result is outside the 
range specified in the FOR statement, the index variable is unaltered 
and execution passes to the statement following the NEXT statement. 

The FOR.. .NEXT loop is then considered complete. A NEXT without a 
preceding FOR with the same index variable produces a runtime error. 

When the compiler option MINANS = YES is selected, and the STEP value 
specified in the FOR statement equals 0, the loop is infinitely 
executed. Upon termination of the loop, the variable equals the first 
value not used (i.e., the last value used within the loop, plus the 
step). 

Syntax Example ; 

100 FOR I = 10 TO 100 STEP 10 
200 PRINT "EXECUTING LOOP" 

300 NEXT I 

400 PRINT "OUT OF LOOP" 
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NUM Function 


General Format: 
NUM (alpha-exp) 


The MUM function determines the number of sequential ASCII characters 
in the specified alpha expression that represents a legal VS BASIC 
number. Numeric characters are defined as digits 0 through 9 and 
special characters E, . (decimal point), +, and space (provided the 
space is not embedded; leading and trailing spaces are considered 
numeric characters, embedded spaces are not). The percent sign {%) is 
not a legal numeric character. Numeric characters are counted 
starting with the first character of the alpha expression. The count 
ends when a non-numeric character occurs, or v/hen the sequence of 
numeric characters fails to conform to standard VS BASIC number 
format. Leading and trailing spaces are included in the count. 

You can use NUM to verify that an alphanumeric value is a legitimate 
VS BASIC representation of a numeric value, or to determine the length 
of a numeric portion of an alphanumeric value. MUM can be used 
wherever numeric functions are normally used. NUM is particularly 
useful when it is desirable to numerically validate input data under 
program control. If A$ = "1E88", MUM{A$) = 16 even though 1E88 is an 
illegal value, since 1E88 exceeds the legal size for a floating-point 
constant. This occurs because NUM checks only format, not value. 


The result of the NUM function is an integer. 


Examples; 


100 A$ = •’98.7+53.6" /* 

200 X = NUM(A$) /* 

/* 

/* 


X = 4 since the sequence of numeric */ 
characters fails to conform to standard */ 
BASIC number format when the + character */ 
is encountered. */ 


100 INPUT A$ 

200 IP NUM(A$) = 16 THEN 500 

300 PRINT’*MON-NUMERIC,ENTER AGAIN" 

400 GOTO 100 

500 CONVERT A$ TO X 

600 PRINT "X = ";X 

Run program: 

? 123A5 

NON-NUMERIC, ENTER AGAIN 

? 12345 

X=12345 


/* The program illustrates */ 
/* how numeric information */ 
/* can be entered as a */ 

/* character string, */ 

/* numerically validated, */ 

/* and then converted to an */ 
/* internal number. */ 
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ON Statement 




General Format: 


ON expression 


/goto \ 

^GOSUBJ 


entry 


[,entryl... 


where: 
entry = 


{ 


line number 
null 

statement label 


The fast entry must be a line number or a statement label (no trailing commas) 


The ON statement is a computed GOTO or GOSUB statement. 

If I is the truncated value of the expression, transfer is determined 
by one of the following the Ith entry options: 

1. If a line number or statement label, the transfer is made to that 
line or statement. 

2. If null, no transfer is made. 

3. If I is less than 1 or greater than the number of entries, no 
transfer is made. 

In options 2 oir 3, execution continues at the next executable 
statement. For example, ON X GOTO,,100,200,,300,,,400 

Value of X Transfer 


-2 

-1 

0 

1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 


none 

none 

none 

none 

none 

100 

200 

none 

300 

none 

none 

400 

none 

none 
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NOTE 


When the compiler option MINANS = YES is selected, the resulting 
expression is rounded to the nearest integer. When I is less than one 
or greater than the number of entries, a diagnostic is generated and 
program execution is terminated. 


Syntax Example : 


100 A = 3 

200 ON A GOTO 300, 400, 500 


300 

PRINT 

"LINE 

300": 

GOTO 

600 

400 

PRINT 

"LINE 

400": 

GOTO 

600 

500 

PRINT 

"LINE 

500": 

GOTO 

600 

600 

PRINT 

"EXIT" 





Result: 

Line 500 
Exit 
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OPEN Statement 


General Format: 


OPEN 


[J 




NODISPLAY \ r, 
NOGETPARMJ 


file-expU 


I 


INPUT 
10 

SHARED 

EXTEND 

OUTPUT 


[,SPACE = num-expl ] [,DPACK = num-exp2] (JPACK = num-exp3) 
[,FILE = alpha-exp 1 ] [.LIBRARY = alpha-exp2] 

[.VOLUME = alpha-exp3] [.FILESEQ = num-exp4] 

[.BLOCKS = num-exp5] 


where: 

alpha-exp 1.2.3 = file, library, and volume names must be enclosed in quotation marks 

Filename = at most 8 characters (remainder ignored) 

Library = at most 8 characters (remainder ignored) 

Volume = at most 6 characters (remainder ignored) 

num-exp5 = size of I/O buffer (in blocks of 2048 bytes) 
default = 1 block 

(use of other parameters explained below) 


Use the OPEN to open an existing disk or tape file or to create a new 
file. Section 8.3.2 discusses the OPEN statement in greater detail. 
The file number (provided by file exp) must appear in a SELECT 
statement (refer to SELECT). BLOCKS is optional, but file, library, 
and volume names are requested by the system (using the SELECT prname) 
even if included in OPEN, unless the file was opened and closed 
previously or NCXjETPARM or NODISPLAY was specified. 


Table II-5 lists the various OPEN modes for old and new files, and the 
allowed I/O operations. 


Attempting to OPEN a file that is already open and has not yet been 
closed causes an irrecoverable error at runtime. 
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The following sections describe using the SPACE, DPACK, IPACK, 
NODISPLAY, NOGETPARM, and FILESEQ fields. 

NODISPLAY, NOGETPARM 

When opening a file in the program, OPEN normally issues a GETPARM 
(refer to the discussion of GETPARM in the VS Procedure Language 
Reference) to the workstation or procedure, requesting the FILE, 
LIBRARY, and VOLUME parameters. You can suppress the prompt at the 
workstation by specifying NODISPLAY. This should only be done if the 
correct FILE, LIBRARY, and VOLUME are specified in this or a previous 
OPEN, or in a procedure, or if SET defaults are in use. (For a 
discussion of SET usage constants, refer to the VS ProqraiTOTer * s 
Introduction .) Both the workstation prompt and the procedure file 
prompt can be suppressed by specifying NOGETPARM. This should not be 
done if the file parameters are to be accessible or modifiable from a 
user procedure. (For a discussion of procedures, refer to the 
VS Procedure Language Reference .) 

The remaining parameters differ in usage depending on v/hether the file 
is being opened in OUTPUT or non-OUTPUT mode. 


SPACE 


OUTPUT: Specifies the approximate number of records to be put in 

the new file. If OUTPUT is not specified, a GETPARM is 
displayed. 

non-OUTPUT: If a variable (i.e., a receiver), it contains the number 
of records currently in the file after OPEN. 

DPACK, IPACK 


OUTPUT: Specifies the block packing densities (integer) for the 

records (DPACK) or keys (IPACK), respectively, for a new 
indexed file only. 

non-OUTPUT: Ignored. 

In any mode, if FILE/LIBRARY/VOLUME are alpha receivers, the actual 
names are returned to the receivers after the OPEN statement is 
completed. 


FILESEQ 


File Sequence number (for tape files only). 
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) 



TYPE 

MODE 

CONSEC 

VAR CONSEC 

INDEXED 

VAR INDEXED 

TAPE 

PRINTER 


Ops: READ.SKIP 

Ops: READ.SKIP 

Ops: READ 

Ops: READ.SKIP 

NOT ALLOWED 

INPUT 

(old 

files 

only) 

Consecutive or 
relative READ 
or SKIP, 
starting from 
beginning of 
file. 

Consecutive or 
relative READ or 
SKIP starting 
from beginning 
of file. 

Consecutive or 
keyed READ, 
starting from 
beginning or 
after last 
record read. 

Consecutive or 
relative READ or 
SKIP starting 
from beginning 
of file. 



Ops: READ,REWRITE, 
SKIP 

Ops: READ.SKIP. 
REWRITE 

Ops: READ.WRITE, 
REWRITE,DELETE 

Ops: READ.SKIP 

NOT ALLOWED 

10 

(old files 
only) 

Consecutive or 
relative READ 
or SKIP starting 
from beginning of 
file, with HOLD/ 
REWRITE option. 

Consecutive or 
relative READ 
or SKIP starting 
from beginning 
of file, with 
HOLD/REWRITE 
option. 

Consecutive or 
keyed READ or 

WRITE starting 
from beginning 
of (key) file, 
with HOLD/REWRITE/ 
DELETE option. 

Consecutive or 
relative READ or 
SKIP starting from 
beginning of 
file, with HOLD 
option. 



Table II-5. Legal Function Requests and Descriptions 
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NOT ALLOWED 

Ops; WRITE. 

HOLD. RELEASE 

Ops: READ,WRITE, 
REWRITE.DELETE 
HOLD. RELEASE 

NOT ALLOWED NOT ALLOWED 

SHARED 
(old INDEXED 
files; 

old or new 

CONSEC files) 

Used for (vari¬ 
able length) 
logjiles. 

Same as 10, but 
allows multiple 
access, indepen¬ 
dently, HOLD 
protection. 


Ops: WRITE 

Ops: WRITE 

Ops; WRITE 

Ops: WRITE Ops: WRITE 

OUTPUT Writes records 

consecutively 
(new files to a new file, 

only) 

(old files 
deleted) 

Writes records 
consecutively 
to a new file. 

Writes records 
to a new file - 
(primary) keys 
must be in as- 
cendingorder. 

Writes records Writes records 

consecutively consecutively 

to a new file. to a new file. 

Ops: WRITE 

Ops: WRITE 

NOT ALLOWED 

NOT ALLOWED NOT ALLOWED 

EXTEND Writes records 

consecutively, 

(old files starting at the 

only) current file end. 

Writes records 
consecutively, 
starting at the 
current file end. 




Table II-5. 


Legal Function Requests and Descriptions (continued) 



3 





Syntax Examples : 

100 OPEN NODISPLAY #1,10,PILE = "THOMAS",LIBRARY = "STEARNS",! 
200 VOLUME = "ELIOT" 

300 OPEN #2,OUTPUT 

400 OPEN NODISPLAY #3, INPUT, VOLUME = "TAPEl", FILESEQ = 1 
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OPTION BASE Statement 


General Format: 

Option BASE n 
where n = either 0 or 1 


The OPTION BASE statement is applicable only v^hen MINANS = YES. This 
statement is not recognized when MINANS = NO. 

The OPTION BASE statement declares the minimum value for all array 
subscripts. When no option statement is executed, the minimum is 
zero. An option statement, if present at all, must occur at a lower 
number line than any dimension statement or any reference to an 
element of an array. When an option statement specifies that the 
lower bound of array subscripts is one, no dimension statement may 
specify a lower bound of zero. A program may contain at most one 
option statement. 


Example 

100 OPTION BASE 1 
200 DIM A$(4,4) 
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The OR operator performs a logical OR operation on two or more 
alphanumeric arguments♦ 


Example: 


100 A$ = "SAINT" 
200 B$ = "S 
300 C$ = A$ OR B$ 
400 PRINT C$ 


Output: 
Saint 


Capital A is HEX{41) (01000001 in binary) and a blank space is HEX(20) 
(00100000 in binary). When two characters are involved in an OR 
operation, a binary one in either becomes a binary one in the result. 
Thus, an A with " " produces binary 01100001 or HEX(61), which is the 
ASCII "a". 


The operation proceeds from left to right. If the operand (logical 
expression) is shorter than the receiver, the remaining characters of 
the receiver are unchanged. If the operand is longer than the 
receiver, the operation stops when the receiver is exhausted. 

Refer to Section 5.7 for more information on logical expressions. 
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General Format: 

PACK PIC (image) alpha-receiver FROM 


J numeric array-designator) [ 

f numeric array-designator) 1 

1 expression ( [ 

1 expression r ‘I 


where: 

image = l±] [#.. .][.][#.. .][(H1 1 (east 1 #) 


The PACK statement packs numeric values into an alphanumeric receiver, 
reducing the storage requirements for large amounts of numeric data 
where only a few significant digits are required. The specified 
numeric values are formatted into packed decimal form (two digits per 
byte) according to the format specified by the image, and are stored 
sequentially into the specified alphanumeric receiver. Receivers are 
filled from the first byte until all numeric data is stored. An 
entire numeric array can be packed by specifying the array with a 
numeric array designator (e.g., N()). An error results if the 
receiver is not large enough to store all the numeric values to be 
packed. 

The image is composed of pound sign (#) characters to signify digits, 
and, optionally, the plus (+), minus (-), decimal point (.), and up 
arrow (T) characters to specify sign, decimal point position, and 
exponential format. The image can be classified into two general 
formats: 

Format Example 

Fixed Point ##.## 

Exponential #.## 

Numeric values are packed according to the following rules: 

1. Two digits are packed per byte. A digit is stored for each pound 
sign (#) in the image. 

2. If a sign (+ or -) is specified, it occupies the high-order 
half-byte. Use a single hexadecimal digit to represent both the 
sign of the number and the sign of the exponent for exponential 
images. The four bits of this hexadecimal digit are set as 
follows: 

Bit 1 (leftmost) set to 1 if exponent is negative 
Bit 2 OFF C’O") 

Bit 3 OFF ("0") 

Bit 4 (rightmost) set to 1 if number is negative 
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3. If no sign is specified, the absolute value of the number is 
stored, and the sign of the exponent is assumed to be positive (+). 

4. The decimal point is not stored. When unpacking the data (see 
UNPACK in this section), the decimal point position is specified 
in the image. 

5. The packed numeric value is left-justified in the alpha receiver, 
with the sign digit (if specified) occupying the high-order 
half-byte, followed by the number in-packed decimal format (two 
digits per byte). The exponent occupies the two low-order 
half-bytes (if specified). The packed value always requires a 
whole number of bytes, even if the image calls for other than a 
whole number. For example, the image "###" calls for 1-1/2 bytes, 
but 2 bytes are required. In such cases, the value of the unused 
half-byte (the low-order half-byte) is not altered by the PACK 
operation. 

6. If the image has a fixed-point format, the value is edited as a 
fixed-point number, truncating or extending any fraction with 
zeros and inserting leading zeros for nonsignificant integer 
digits according to the image specification. An error results if 
the number of integer digits exceeds the format specification. 

7. If the image has an exponential format, the value is edited as an 
exponential number. The value is scaled as specified by the image 
(there are no leading zeros). The exponent occupies one byte, and 
is stored as the two low-order hex digits in the packed value. 


Example of Storage Requirements : 


#### 

### 

+##.### 

+#.## 


= 2 bytes 
= 2 bytes 
= 3 bytes 
= 2 bytes 


Syntax Examples : 

100 PACK PIC (####)A$ FROM X 

200 PACK PIC (####)STR(A$,4,2) FROM N(l) 

300 PACK PIC (##.##)A1$() FROM X,Y,N(),M() 
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$PACK/$UNPACK Statements 


General Formats: 
$PACK 



alpha-receiver FROM arg[,argl... 

[ .data |gosub 

- 

. 1 line number L 

1 ^ statement label j 



where; 

{ line number = line number or statement label of 

statement label | data conversion error exit 

fexp 


arg = < alpha-exp, EXCEPT alpha array string 
[array-designator 


$UNPACK ( 


[{?:}] 


alpha-exp) alpha-exp TO argl.arg] 


/goto \ 

/ line number ) 

\gosub/ 

\ statement label | 


where: . 

_ f receiver, EXCEPT alpha array string 1 
^ I array-designator j 


K 






$PACK and $UNPACK pack and unpack numeric and character data, in any 
of several formats specified by you, into the alpha receiver or from 
the alpha expression, respectively. 

The following considerations apply to $PACK and $UNPACK operation: 

1. An argument of the form "name${)" is always recognized as an array 
of elements, never as an alpha array string. Use the STR function 
to produce an array string. 

2. Array elements are generally considered as individual consecutive 
values or receivers (row by row). The exception is F format, in 
which a single format applies to all of the array elements. 

3. $PACK generates an error (or exit) if the alpha receiver is not 
long enough to store all of the arguments in the specified 
format. This is true with any of the formats. 

4. $UNPACK generates an error (or exit) if the unpacked data is not 
the same type (alpha, numeric) as the receiver. 
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Delimiter Format 


The delimiter format is indicated by the presence of 

"D = alpha-expression". The format of the data packed by $PACK is: 


data 

DEL 

data 

DEL 


data 

DEL 


where DEL is the user-specified delimiter. 

The alpha expression follov/ing "D =" must contain at least two bytes: 

• byte 1 = Conversion code. This is used only by $UNPACK, but it 
must have one of the following four legal values for 
either SPACK or SUNPACK: 


Hex Value 

($WJPACK) Result 

00 

A) 

Error if insufficient data is in the buffer. 


B) 

Skip a receiver (or array element) for each extra 
delimiter encountered. 

01 

A) 

No error if insufficient data in the buffer — 
remaining receivers are left unchanged. 


B) 

Skip a receiver for each extra delimiter. 

02 

A) 

Error if there is insufficient buffer data. 


B) 

Ignore extra delimiters. 

03 

A) 

No error if there is insufficient buffer data. 


B) 

Ignore extra delimiters. 


• byte 2 = (DEL) delimiter character. 

1. $PACK: The general form is shown in the General Format section. 

The structure of the data entries is as follows: 


a. Numeric — Exactly like PRINT, without the trailing 
blank. 

b. Alphanumeric — Defined length is stored. 
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2. $UNPACK: Extra delimiters can be present, as described in the 

conversion code. A missing final delimiter causes the 
last data value to be considered as extending to the 
(defined) end of the buffer (alpha expression). The 
specific data entries allowed are: 

a. Numeric — Can be any numeric constant that is allowed 

on a program line, including leading and trailing 
blanks. Exception: as with CONVERT, is not 

recognized as a legal character. 

b. Alphanumeric — Can be anything of any length. 
Alphanumeric entries are right padded or truncated to 
fit the receiver. 


NOTES 


$UNPACK condition code can be set not to cause an error if there are 
too few data values in the buffer; this is true only for delimiter (D) 
format. In any of the other formats, an error (or DATA exit) results 
if the buffer has insufficient data. 

Any errors in executing $PACK and $IINPACK do not affect values already 
packed or unpacked in the same statement. As is the case with 
regular PACK and UNPACK statements, the error occurs only when the 
first erroneous conversion is encountered. 


Field Format 


Indicated by the presence of "F = alpha-expression". The format of 
the data packed by $PACK is: 


field 

field 

field 

... 

field 

field 


where field = a skip field 

a formatted data value 

The alpha expression following "F = " must contain at least as many 
pairs of bytes as there are arguments in the argument list. (Each 
pair corresponds to an argument, whether it is a scalar or array 
argument.) 
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From left to right, each argument has a corresponding byte pair, in 
which: 

1, byte 2 = field width (bytes) in hex > 0 

2. byte 1 = field type 

Byte 1 Value Resulting Field Type 

00 skip field 

10 free-format 

2hp ASCII integer format 

3hp IBM display format 

4hp WANG display format 

5hp IBM packed decimal format 

AO alphanumeric field 

(hp = the number (in hexadecimal) of places to the right of the 
implied decimal point.) 

The field types are discussed here. 

Field Types 




1. 00 — Skip 

In either $PACK or $t]NPACK, skips the specified number of bytes in 
the buffer; skipped characters are unchanged. 

2. M — Alphanumeric 

For alphanumeric data; in either $PACK or $UNPACK, the value is 
padded or truncated on the right to fit the field or receiver, 
respectively. 

3. — Free-Format ASCII Numeric 

$PACK; Same as delimiter format (i.e., same as PRINT) but 
right-padded or truncated to fit the field. 

$UNPACK: Same as delimiter $IJNPACK fields. 
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4. — ASCII Implied Decimal 


Form: 





where d = (ASCII) digit 0 through 9 
s = sign byte 

$PACK: format as shown; sign byte is ASCII 
(+ = HEX(2B), - = HEX(2D)). 

$UNPACK: format as shown; all the zone half-bytes are ignored so 
that they can have any value. 

5. — IBM Numeric Display Format 

Form: 


Fh 

Fh 

Fh 

... 

Fh 

Fh 

hs h 


h = hexadecimal digit from 0 to 9 only 
hs = sign digit 

$PACK: format as shown 

hs = C (+) 

D (-) 

$UNPACK: format as shown; Fs are ignored. 

hs = A,C,E,F {+> 

B,D (-) 
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6. — WANG VS Display Format 






Form; 


3h 

3h 

3h 

... 

3h 

3h 

hs h 


h = hexadecimal digit from 0 to 9 only 
hs = sign digit 

$PACK: format as shown 

hs = F (+) 

D (-) 

$UNPACK: format as shown; 3s ignored 

hs = D {-) 

all else (+) 

7. — IBM Packed Decimal Format 


Form: 


hh 

hh 

hh 

... 

hh 

hh 

hhs 


h = hexadecimal digit from 0 to 9 only 
hs = sign digit 

$PACK; format as shown; hs = C {+) 

D (-) 

$UNPACK: format as shown; hs = A,C,E,F (+) 

B,D (-) 
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Field types 4 through 7 have the following characteristics in common; 


• In $PACK, an overflow causes an error, but the field is filled with 
zeros and the correct sign. 

• In 2hp, 3hp, and 4hp zoned format, zones are not checked when 
$UNPACKed, and thus can take on any values. This includes the zone 
of the sign byte in 2h format. One consequence of this is that 
blanks are interpreted as zoned zeros in 2hp, 3hp, and 4hp. 

• h in the format specification denotes the number of p digits to 
the right of the implied decimal point. It can take on any 
hexadecimal digit value, and can be larger than the number of digits 
in the field {in which case leading decimal zeros are implied). 

• In $PACK, an underflov/ causes no error and fills the field vfith 
zeros and a plus sign (+), regardless of the sign of the expression 
itself. 

• $PACK inserts leading and trailing zeros where necessary. 

• $UNPACK allows any number of digits. Only the first 15 significant 
digits are used; the rest only serve to position the decimal point. 

2200 Disk Storage Format 

Indicated by the absence of both D and F. 

Form; 






sov 


data 


SOV 


data 


SOV 


data 


BOB 


CONTROL 


where; 


CONTROL = Pseudo-2200 control bytes (2) 
data = numeric or alpha value 
EOB = end-of-block byte 
= HEX(FD) 

SOV = 2200 Start-of-value byte for the next data value 


1 nn I I I I I I I I I 

S <-L-> 

where; 

S = 0 = numeric L = length in bytes (binary) 

1 = alpha 
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$PACK Data Format 




1. Numeric 


Form: 


hshu 

hthi 

haha j 

h4h5 

hshT 

1 hshs 

hiohi1 

hiahi3 


Value is decimal floating point. 

hs = sign indicator 

= 0, number +, exponent + 

1, number exponent + 

8, number +, exponent - 

9, number exponent - 

hu ht = exponent (units before tens) 

hi to hi 3 = mantissa, in the usual order, with the decimal 

point assumed between hi and hj. 




2 . 


Alphanumeric 

Form: 



The defined length is stored. 
3. Control bytes — HEX(8001) 
$UNPACK Data Format 


1. Numeric — Same as $PA(3C, but allows any sign digit: 

$PACK $UNPACK 

0 0 , 2 , 4,6 

1 1,3,5,7 

8 8,A,C,E 

9 9,B,D,F 

This occurs because the two middle bits of the hexadecimal digit 
are ignored. 

2. Alphanumeric — Any length, padded or truncated on the right to 
fit the receiver. 

3. Control bytes — Ignored. 
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Syntax Examples : 


100 $PACK <D = D$)B3$() FROM T1,T1$(>,T3$,T2,DATA GO TO 210 
200 $UNPACK (D = D4$(l)) STR{B3$(),,15) TO T$(),DATA GO TO 210 
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PI Intrinsic Constant 




General Format: 
PI 


The intrinsic constant PI can appear anywhere a numeric expression can 
appear. It has the value 3.14159265358979323. 


Syntax Example : 

100 AREA = PI * RADIUS?2 
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POS Function 





The POS function searches the first alpha expression for a character 
that bears the appropriate relationship (<, <=, >, >=, <>, or =) to 
the first character of the second alpha expression and returns the 
location (leftmost = 1) of the first such character found. The basis 
of comparison is the ASCII codes of the characters. POS searches the 
entire defined length of the alpha-expression. 

If no minus sign (-) is present, the search executes from left to 
right, and returns the position of the leftmost such character. If 
the minus sign {-) is present, the search executes from right to left, 
and returns the position of the rightmost character. 

If no character satisfies the condition, POS = 0. The output of POS 
is an integer . 

Syntax Examples : 

100 A% = P0S(-A$ < STR{B$,2,2)) 

200 FOR A = 1 TO 10 STEP POS{C$ = B$) 
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PRINT Statement 






General Format: 

[using 


PRINT 


where: 


expression] 


{ line no. 1 [. 

stmt label j I 

r.-* ai* - J character prt-elt 1 
I control prt-elt | 


{■} 


[expression] 


[prt-elt] 


{ num-exp 
alpha-exp 
HEXOF (alpha-exp) 


control prt-elt = 


{ BELL 
PAGE 

SKIP[(num-exp)] 

TAB (num-exp) 

COL(num-exp) 

AT (num-exp, num-exp [,[ num-exp]]) 



The PRINT statement routes output to either the workstation or 
printer, depending on which device is currently selected (refer to the 
SELECT statement in this section). 

The placement and format of the data that is output are controlled 
either by the use of auxiliary format control (FMT and Image {%)) 
statements, or by the use of the control print elements described in 
the following paragraph. If a format control statement is used, the 
PRINT statement must contain a USING clause referring to the FMT or 
Image {%) by line number or statement label. 

In either case, output begins at the current print position, as 
determined by the last output operation to the selected device 
(current print position is indicated on the workstation by the 
position of the cursor). After the PRINT statement is executed, the 
new current print position depends on how the PRINT statement ends. 

If the PRINT statement ends in a semicolon, a comma, or a control 
print element (prt elt), the current print position is the first 
position after the last character output; otherwise, the current print 
position is the first position of the next line. 
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For PRINT output, the output line is divided into as many zones of 18 
characters as possible; thus, a 132-column printer has seven zones, 
and the workstation has four. The last zone can be longer than the 
rest, extending to the end of the line. 

Expressions and other print elements in a PRINT statement must be 
separated by commas or semicolons. If USING is specified, these are 
equivalent and serve only to delimit one expression from the next. If 
USING is omitted, however, a comma after a character print element 
causes the next print element to begin at the start of the next zone 
(if the current print position is already in the last zone of a line, 
the next print element starts at the beginning of the next line). 

When the compiler option MINANS = YES is selected and the next print 
position on the current line is the first position of a zone, a comma 
in the print list causes the next print element to begin at the start 
of the next zone. 

A semicolon causes no change in print position. After a control print 
element, commas and semicolons are equivalent. 

A line is not sent to the printer until either the print position is 
moved beyond the line or a SKIP(O) is encountered. See Chapter 7 for 
more information on output to the workstation and printer. 

The following discussion of print elements does not apply to PRINT 
statements that specify USING. For details on the operation of the 
USING clause, see the entries for the FMT and Image\(%) statements. 

Print Elements 


1. Numeric Expression 

a. If I exp I <10"^ or lexpl>=10*®, the format is exponential: 
SMDMMMMMMMMMME + XXb 

where: S = minus sign if negative, blank otherwise 
M = mantissa digit 
D = decimal point 
XX = exponent digits 
b = blank 

For example, PRINT .000074679; 

Result: 

b7.4679000000E-05b 
start end 
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b. If 10 ^ <= I exp I < 10^^, the format is fixedpoint: 

S[Z,,.][DF...]b 

where: S = minus sign if negative, blank otherwise 
Z = zoned digit 
D = decimal point 
F = fixed digit 
b = trailing blank 

and total Zs + total Fs <= 15» 

Leading zeros and trailing (decimal) zeros are not printed (but 
zero is printed as ’bOb*). Up to 15 digits plus a decimal point, 
if any, are printed. 


MOTE 


When the compiler option MINAMS = YES is selected, the PRINT statement 
uses the unsealed format for numbers with negative exponents when 
maximum significance can be preserved. 


2. Alpha Expression 

The actual length of the alpha expression is printed. Trailing 
blanks of an alpha variable or array string are not printed. 

3. HEXOF (alpha expression) 

The hex value (defined length) of the alpha expression is 
printed. (This includes trailing blanks — HEX(20).) For example, 

100 DIM A$ 5 
200 A$ = "ABC" 

300 PRINT "HEX VALUE OF A$ =";HEX0F (A$) 

Result: 

HEX VALUE OF A$ = 4142432020 

4. PAGE 


Printer : Advances to line 1, column 1 of a new page. 
Workstation: Clears the screen and moves the cursor home. 
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5. BELL 


Printer ; Ignored. 

Workstation ; Sounds the workstation alarm; the screen and cursor 
are unaffected. 

6. SKIP [(n)] 


Printer ; Advances the print position to column 1 of the nth line 
after the current line (default n=l). 

If n = 0, the current line is printed with a carriage return but 

no linefeed. This causes the next line to overprint. 

If n < 0, SKIP is ignored. 

Workstation : Advances the cursor print position to column 1 of 
the nth line after the current line (default = 1). 

If n > 0, the cursor moves down n lines. In cases in which the 
cursor must move to a line off the screen (i.e., current 
line + n > 24), a rollup occurs instead. The cursor is positioned 
at the beginning of the last line moved to (the bottom line of the 
screen if one or more rollups occurred). 

If n = 0, the cursor returns to the beginning of the current line. 

If n < 0, the cursor moves up n lines. A move to a line off 

(above) the screen causes a rolldown. The cursor is positioned at 
the beginning of the last line moved to (the top line of the 
screen if 1 or more rolldowns occurred). 

7. TAB(n) 


Printer ; (n > 0). The print position advances to column n of the 
current line. If the column was passed already, the TAB is 
ignored. 

Workstation ; (n > 0). The cursor is moved to column n of the 
current line, erasing passed-over characters (overwriting them 
with space characters). If the column was passed already, the TAB 
is ignored. 

In either case, if the tab position is greater than the line 
length indicated in the SELECT statement (always 80 characters for 
the workstation), the print position advances to column 1 of the 
next line. If n is negative or zero, the TAB is ignored. 
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When the compiler option MINANS = YES is selected, and a TAB to a 
column less than the current column is generated, printing starts 
at the specified column on the next line. The arguments to TAB 
are rounded. 

Additionally, when a TAB<n) is issued where n is greater than the 
length of the line, and the current position is the start of the 
line, the current position is moved to n modulo line length. 

8. COL(n) 


Like TAB, but does not erase any passed-over characters. (TAB and 
COL are equivalent for the printer, since characters cannot be 
erased.) 

9. AT(r, c[, [e]]) 


Printer : Ignored 

Workstation : AT(r,c[,[e]]) moves the cursor to row r, column c of 

the screen, and optionally erases e characters starting at (r,c). 

The following rules hold: 

a. 1 <= r <= 24. 

b. 1 <= c <= 80. 

c. e>0; if e is greater than the number of characters from the 
cursor position to the end of the screen, only characters to 
the end of the screen are erased. 

d. If e and the preceding comma are omitted, no erasure occurs. 

If e is omitted but the preceding comma is included, the rest 
of the screen is erased, starting from (r,c). 

Note that AT, like COL, has no effect on passed-over characters. 

Syntax Examples : 

100 PRINT A$, B$ 

200 PRINT USING 600, A, B, C 
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PUT Statement 




General Format: 


PUT \ 

I alpha-receiver j 


lUSING line number],arg[,arg]... 


nATA \ /linenumber 1 

,UAi A S goSUB j ^ statement label j 


where: 

fexp 

arg = < alpha-exp 




array-designator J 


PUT inserts data into the record area or alpha receiver using the 
Image {%) or FMT reference in the USING clause, if specified, or using 
standard format. 

PUT does not destroy values not explicitly overwritten. Data inserted 
into a record area with PUT can be written to the file by a subsequent 
WRITE or REWRITE statement. 

The DATA exit is taken if a data conversion error occurs. 

Syntax Example ; 

10 SELECT #1 "EXAMPLE" CONSEC, RECSIZE = 16 

20 OPEN #1 EXTEND, FILE = "EXAMPLE", LIBRARY = "DATA",VOLUME = "VOL444" 
30 PUT#1,B$ 


NOTE 


Use PUT to convert numeric data to a format acceptable to COBOL 
programs. See Appendix D for information on numeric data 
compatibility between BASIC and COBOL. 
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RANDOMIZE Statement 


General Format: 
RANDOMIZE 


The RANDOMIZE statement is available only when the compiler option 
MINANS = YES is selected. This statement overrides the predefined 
sequence of pseudorandom numbers generated by the RND function. 
(Refer to Section 4.4.1 for more information on the generation of 
unpredictable sequences of pseudorandom numbers.) Using this 
statement allows different and unpredictable results each time the 
program is executed. 

Executing the RANDOMIZE statement generates a new unpredictable 
starting point to the list of pseudorandom numbers used by the RND 
function. 


Syntax Example: 

100 RANDOMIZE 
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READ Statement 


General Format: 

READ receiver (,receiver]... 


A READ statement causes the next available elements in a DATA list 
(values listed in DATA statements in the program) to be assigned 
sequentially to the receivers in the READ list. This process 
continues until all receivers in the READ list receive values or until 
all the elements in the DATA list are used. Each receiver must 
reference the corresponding type of data or an error results. 

You must use the READ and DATA statements together. If a READ 
statement references more receivers than the number of elements in a 
data list, the system uses the next DATA statement in statement number 
sequence. If there are no more DATA statements in the program, an 
error occurs and the program is terminated. 

The RESTORE statement resets the DATA list pointer, allowing values in 
a DATA list to be reused (see RESTORE). 


NOTE 


A DATA statement can occur anywhere in the program as long as it 
provides values in the correct order for the READ statement(s). 


Syntax Examples : 

100 READ A,B,C 
200 DATA 4,315,-3.98 

100 READ A$,N,B1$(3) 

200 DATA "ABODE",27,"XYZ” 

100 FOR I = 1 TO 10 
110 READ A(I) 

120 NEXT I 

200 DATA 7.2, 4.5, 6.921, 8, 4 
210 DATA 11.2, 9.1, 6.4, 8.52, 27 
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READ File Statement 








General Format: 



r 


(KEYtexpl) |>=| 

alpha-exp 11 

READ file-exp 

LIHOLD 

[.1 

1 1 =/ 
tRECORD=exp2 

/I 


Fnn /goto \ /line number \ r»ATA /gOTO \/line number \1 
' ^GOSUB j \ statement label j I ' ^GOSUB j ^statement label j I 


where: 

HOLD = hold record for REWRITE or DELETE. The record is held exclusively if in 
SHARED mode; i.e., no other user may access the record until REWRITE, 
DELETE, or another READ HOLD is executed 

expl = alternate key number for keyed READ on alternate indexed file 
(primary key used if expl = 0 or is omitted) 

alpha-exp 1 = indexed file key specifier; the first record whose key satisfies the condi¬ 
tion is read. Only as many characters as specified in KEYLEN are com¬ 
pared; if the alpha-exp is shorter (defined length) than KEYLEN, only as 
many characters as its length are compared 

exp2 = record number (from 1) for CONSEC files only 


USING 


i 


line number | 

t statement 
label 


> = 


J 


line number or statement label of FMT 
or Image statement describing the input 
data format 


arg = 


- X 


receiver 
\ array-designator ( 


\ 


K 


f 


Data are moved (and optionally converted) into consecutive receivers 
EOD = end-of-data or invalid key exit, overriding the SELECT EOD 
data = data conversion error exit 
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The READ Pile statement causes a record in a disk or tape file to be 
read. An OPEN statement must have already opened the file (refer to 
OPEN statement in this section). 

If neither KEY nor RECORD is specified, the next consecutive record is 
read (using the established reference key in the case of alternate 
indexed files, that is, the last used in a READ KEY statement). 

If no argument list is present, the data is left unconverted in the 
record area, and is accessible only through GET. 

If USING is omitted, data is assumed to be in internal format. 

(Refer to Section 8.4.7.) 

Syntax Example : 

SELECT #1 "EXAMPLE" CONSEC, RECSIZE=16 

OPEN #1 INPUT, FILE = "EXAMPLE",LIBRARY = "DATA" VOLUME = "VOLUME" 

READ #1,B$ 






11-144 VS BASIC Statements and Functions 



REM[ark] Statement 


r^ 



You can use the REM statement to insert comments or explanatory 
remarks in the program. When the compiler encounters a REM statement, 
it ignores the remainder of the statement, but not necessarily the 
rest of the line, as the following examples (lines 210 and 300) show. 


NOTE _ 

When the compiler option MINANS = YES is selected, colons are not 
treated as end of statement indicators in REM statements. 




it ax Examples: 


100 REM SUBROUTINE 

210 REM FACTOR: F=Y/(X+1) 

220 REM THE NUMBER MUST BE LESS THAN 1 
300 REM - :PRINT "ERROR":REM STOP:STOP 


The statements after the colon in line 210 and after the first and 
third colons in line 300 are executed. 


REM or REMARK are both acceptable statements. 
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RESTORE Statement 


General Format: 


RESTORE 



{ line number 
statement label 



where: 

{ line number 1 _ line number or statement label of a DATA statement in the 

statement label j program. If omitted, the first DATA statement is used 

1 < = exp < = total number of DATA items in the program, beginning at the given line, 
if specified. If omitted, default = 1 


The RESTORE statement allows READ statements to use DATA statements 
repetitively. When a RESTORE statement is encountered, the system 
resets the DATA pointer to the specified DATA value. A subsequent 
READ statement reads data values beginning with the specified value. 

When a RESTORE statement is encountered, the system resets the DATA 
pointer to the (expression) data value in the program, beginning 
either at the first DATA statement (if LINE = is omitted) or at the 
DATA statement at the specified line number or statement label. 

If expression is omitted, the pointer is set to the first data value 
in the program or in (or beyond) the specified DATA statement. 

The following program, for example, 

100 DATA 1,2,3 
200 DIM A(l,10) 

300 FOR I = 1 TO 10 

400 IF I >= 6 THEN RESTORE LINE =700, 3 
500 READ A(1,I) 

600 NEXT I 
700 DATA 4,5,6 
800 MAT PRINT A; 

produces the following output: 

1234566666 
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Syntax Examples 


100 

RESTORE 



200 

RESTORE 

5 


300 

RESTORE 

(X - 

Y) / 2 

400 

RESTORE 

LINE 

= 100 

500 

RESTORE 

LINE 

= 100, 
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RETURN Statement 




General Format: 
RETURN 


Use the RETURN statement in a subroutine to return processing of the 
program to the statement following the last executed GOSUB or GOSUB' 
statement. 

If a Program Function (PF) key was used to enter a marked subroutine, 
the RETURN statement returns control to the interrupted INPUT or STOP 
statement. 

Do not enter subroutines repeatedly without executing a RETURN. 

Failure to return from these entries causes return information to be 
accumulated. This can eventually cause a stack overflow and premature 
termination of the program. (Refer to the RETURN CLEAR statement in 
this section.) 

Examples : 

100 GOSUB 300 

200 PRINT X:STOP 

300 REM THIS IS A SUBROUTINE 

400 - 

500 - 


900 RETURN:REM END OF SUBROUTINE 

100 GOSUB'03(A,B$) 

200 END 

300 DEFFN’03(X,N$) 

400 PRINT USING 500,X,N$ 

500 % COST = $#,###,###.## CODE = #### 
600 RETURN 
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RETURN CLEAR Statement 


General Format: 
RETURN CLEAR [ALL] 


The RETURN CLEAR statement clears from memory the return-address 
information generated by the last executed subroutine call or by all 
executed subroutine calls. 

The RETURN CLEAR statement is a dummy RETURN statement. The RETURN 
CLEAR statement causes subroutine return address information from the 
last previously executed subroutine call to be removed from the 
internal tables. The program then continues at the statement 
following the RETURN CLEAR. 

If RETURN CLEAR ALL is specified, all subroutine return information is 
removed from the program stack. A RETURN or RETURN CLEAR cannot be 
executed before a subsequent GOSUB or GOSUB'. 

The RETURN CLEAR statement avoids memory stack overflow when a program 
repeatedly exits from subroutines without executing a RETURN. This is 
particularly useful when using the PF keys to control program 
execution (from either STOP or INPUT). When a PF key is used in this 
manner, a subroutine branch is made to the appropriate DEFFN' 
statement to continue execution. 

A subsequently executed RETURN statement causes the STOP or INPUT 
statement to be repeated automatically. However, you may want to 
continue a program without returning to the STOP or INPUT. In this 
case, use the RETURN CLEAR statement to exit from the DEFFN' 
subroutine. Executing a RETURN CLEAR statement when not inside a 
subroutine results in an error. 

Syntax Example ; 

100 DEFFN'15 
200 RETURN CLEAR 
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REWRITE Statement 


General Format: 

REWRITE file-exp [ [,] SIZE = exp] [ LI MASK = alpha-exp 1 ] 



LlUSiNG 

j line number 
\ statement label ( 

,argLarg]... 


- 

V / J 



nATA JgOTO Ijline number I 
' "|GOSUBj "^statement labelj 


where: 

I iciNir' / line number 1 
^statement label I 


line number or statement label of 
FMT or lmage(%) describing the 
output format 


arg = 


{ num-exp 
alpha-exp 
array-designator 


DATA = data conversion error exit 


Use the REWRITE statement to overwrite an existing record. The 
existing record must have been read with the HOLD option. 

If the argument list is omitted, it is assumed that a PUT statement 
formatted the record in the record area. If the argument list is 
present, it is converted value by value, using the Image {%) or FMT 
statement (if specified). Otherwise, the standard format is used. 

Direct concatenation operations within the REWRITE statement are 
illegal in VS BASIC. 

If the file is not an INDEXED VAR[C] file, the rewritten record size 
is the same as that of the overwritten record; SIZE and the implicit 
argiament list size are ignored. If the file is an INDEXED VAR[C] 
file, the size of the rewritten record is determined in one of the 
following ways: 

1. Record size equals SIZE expression, if included. 

2. Record size equals resultant size of the formatted argument list, 
if specified (see WRITE). 
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3. If the argument list is omitted, the rewritten record is the same 
size as the record it overwrites. 

REWRITE is not allowed for CONSEC VARC files. 

Use MASK to set the alternate key mask for alternate indexed files. 
(Refer to the explanation of the MASK function in 
Section 8.5.3 for more information.) If MASK is omitted, the 
alternate key mask for the record is rewritten unchanged. 

Syntax Examples : 

100 REWRITE #1,SIZE = A,MASK = MASK(#2), USING 300,A$,B,C% ! 

200 DATA GOTO 1000 

300 FMT CH(20), PIC{##.#}, PD<3) 
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RND Function 


General Format: 
RND (numeric exp) 


Use the RND (random number) function to produce a pseudorandom number 
between 0 and 1. The term "pseudorandom” refers to the fact that VS 
BASIC cannot produce truly random numbers. Instead, it relies on an 
internal algorithm that uses the last random number to generate the 
next one. The resulting sequence (list) of values, though obviously 
not truly random, is scattered in the range zero to one in such a 
manner as to appear to be statistically random. 

When the compiler option MINANS = YES is selected, the RND function 
requires no argument to generate the next pseudorandom number between 
zero and one. When this function is used with the RANDOMIZE 
statement, unpredictable sequences of pseudorandom numbers are 
generated. When the RANDOMIZE statement is not used, each sequence of 
execution of the RND function in each program's invocation generates 
the same sequence of pseudorandom numbers. 

When the compiler option MINANS = NO is selected, there are three ways 
to use RND(exp), based on the value of the argument: 

1. exp < 0 or exp >1 — Produces the next pseudorandom number in the 
list as produced by the internal algorithm. If this is the first 
use of RND in the program, the compiler sets the previous value at 
compilation. 

2. 0 < exp <1 — Returns exp as the result and resets the list to 
this value. 

3. exp =0 — Similar to option 2, but produces a number computed 
from the time of day when the RND is executed, rather than from a 
user- or compiler-specified value. 

Refer to Section 4.4.1 for more information on RND. 

Examples : 

100 A = RND(.5) 

200 B = RND(2) 

300 C = RND(l) 

400 PRINT "A = ";A,"B = ";B,"C = ";C 
Result: 

A = .5 B = .259780899273209 C = .298807370711264 
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ROTATE[C] Statement 




General Format: 

ROTATE[C] (alpha-receiver, numeric exp) 
where: 

-8 < = numeric exp < = 8 


The ROTATE[C] statement rotates bits in the given alpha receiver. If 
the expression is less than zero, rotation is left to right. If the 
expression is greater than zero, rotation is right to left. Bits that 
are moved past one end of the receiver are moved to the other end of 
the receiver. 

If C is not specified, rotation occurs for each byte in the receiver. 
If C is specified, the entire receiver is rotated. 

ROTATE operates on the defined length of the alpha receiver. 

Examples ; 

100 DIM A$5 

200 A$ = HEX(345678AD) 

300 ROTATE (A$,4) 

400 PRINT HEX0F(A$) 

Result: 

436587DA02 

500 ROTATEC (A$,-8) 

600 PRINT HEXOF (A$) 

Result: 

02436587DA, assuming the previous result 
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ROUND Function 


General Format; 
ROUND (exp,exp) 


ROUND{X,N) is equivalent to the expression: 
SGN(X)*{INT(ABS(X)*10**N%+0.5)/10**N%) 


Its effect is to round off the value of X to the precision specified 
by N. If N is positive, X is rounded off to N decimal places. If N 
is negative, X is rounded off to the Nth place to the left of the 
decimal point. If M is not an integer, it is truncated. For example. 

Numeric Examples : 


ROUND<123 
ROUND(123 
ROUND(123 
ROUND(123 
ROUND(123 
ROUND(123 
ROUND(123 
ROUND(123 


4567,4) 

4567,3) 

4567,2) 

4567,1) 

4567,0) 

4567,-1) 

4567,-2) 

4567,-3) 


123.4567 
123.4570 
123.4600 
123.5000 
123.0000 
= 120.0000 
= 100.0000 
= 0 etc. 


Unlike the INT function, the ROUND function rounds upward. For 
example, rounding 4.7 to zero decimal places produces a 5 with the 
ROUND function, but a 4 with the INT function. 

Syntax Example : 

100 Y = R0UND(X,5) 
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SEARCH Statement 


General Format: 

r 

<= 


SEARCH [-] alpha-expl -< 

> 

>= 

<> 

^ “ > 

alpha-exp2 

jQ f numeric array-designator (STEP numeric exp) 1 

y alpha-receiver / 


SEARCH searches alpha expl (defined length) for substrings of the same 
length as alpha exp2 (actual length) that satisfy the given relation. 

If the minus sign (-) is not specified, the SEARCH begins with the 
substring starting at the leftmost byte (byte 1) of alpha expl; each 
subsequent substring checked has a starting byte n bytes to the right 
of the previous substring, where n is the value of the STEP expression. 

If the minus sign (-) is specified, the SEARCH begins with the 
rightmost substring, that is, starting at the (defined length 
alpha expl minus actual length alpha exp2 +l)th byte of alpha expl. 
Subsequent substrings have a starting byte n bytes to the left from 
that of the previous substring. 

If STEP is omitted, n = 1 and all substrings are checked. 

SEARCH terminates when it runs out of substrings of the proper length 
or reaches the limit of the TO argument. If expl is initially too 
short, no substring is checked. 

Upon completion, the TO argument contains the starting positions of 
the substrings found (from 1) in one of the following formats: 

1. If "numeric array designator", the array contains the numeric 
starting positions in the order in which they were found. The 
first unused array element (if any) contains 0. Any other unused 
elements remain unchanged. 

2. If "alpha receiver", each pair of bytes contains the 2-byte binary 
representation of the starting positions, as in option 1. The 
first unused pair of bytes (if any) will contain binary 0. Any 
other unused bytes remain unchanged. 
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In either case, if the array or receiver is too short to contain all 
positions found, the remaining positions are lost. 




Example : 

100 DIM A$40, N(l,8) 

200 A$ = "SESSIONS OF SWEET SILENT THOUGHT" 
300 SEARCH A$ = STR(A$,1,1) TO N() 

400 SEARCH -A$ = STR(A$,1,1) TO B$ 

500 PRINT HEXOF(B$) 

600 MAT PRINT N 

Output: 

0013000D000800040003000100002020 
13 4 8 

13 19 0 0 
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SELECT Statement 






General Format: 


SELECT select-elt Lselect-elt] (...] 


where: 


select-elt = 


PAUSEtd] 

RADIANS 

DEGREES 


J GRADS 

PRINTER [{exp)] 

CRT 

WS 

^ POOL file number[,flie number]. 




> 


.,BLOCKS=int ) 


PAUSE[d] = d/10 second execution pause after each write to the 
workstation. If d=0 or is omitted, no pause. System 
default = no pause, d must be an integer. 


RADIANS 1 
DEGREES > 
GRADS j 


trig arguments/results in radians, degrees or grads, 
respectively. {360 degrees = 2 radians = 400 grads.) 
System default = radians. 


printer! 

CRT > 
WS J 


route print output {PRINT, PRINTUSING, etc.) to the 
line printer or workstation, as specified. If no 
SELECT has been executed, output is routed to 
the workstation by default. 

exp can be used following PRINTER to specify 
nonstandard printer line width, where 1 < = exp < = 162 
{if omitted or invalid, default = 132). 


POOL 

BLOCKS 

int 


a buffer pool for the specified files. {Files must 
be indexed) 

the number of 2048-byte buffers in the pool, 
an integer from 1 to 255. 


The SELECT statement allows you to define a number of programming 
options. The SELECT statement can set the length of time the 
workstation pauses after each write, the units for trigonometric 
calculations, the output device for PRINT and related statements, 
and/or buffer-pooling options. 
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A POOL specification can only appear after the SELECT File statements o 

for the pooled files, and a particular file number can only be 

included in a single POOL. Only indexed files opened in Input or 10 

modes can be pooled. Otherwise, this statement can be used anywhere 

and as often as desired. The select elts are processed one at a time, 

from left to right. 

Syntax Example ; 

100 SELECT PAUSE 9,PRINTER,DEGREES,P00L#1,#2,BLOCKS = 2 


r^ 
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SELECT File Statement 






General Format: 


SELECT file-number 


"prname"Ll 


f Consecutive'! 
J indexed 
I Tape 
V Printer 


[JOERR exit] 


where: 

File-number = #n, where n is an integer from 1 to 64 
prname = 1 to 8 characters (alphanumeric, including @,#,$) 
Consecutive = (VAR[C][,]] CONSEC, RECSIZE = inti (,EOD exit] 


Indexed = [VAR[C](,]] INDEXED, RECSIZE = inti, KEYPOS = int2. 


KEYLEN = intS 


/alternate 

1 ALT 


} 


alt-spec[,alt-spec...] 


alt-spec = KEY int4, KEYPOS = int5. KEYLEN = int6 [,DUP] 
int4 = 1 to 16, may not be repeated. 


[,EOD exit] 


Tape = (VAR[C][,]] TAPE, 



RECSIZE = int7, BLKSIZE = int8. 


(800 1 

DENSITY = < 1600 > LEOD exit] 
(6250 J 


Printer = PRINTER, RECSIZE = intlO 


exit = 


_ /GOTO \ /line number 


|GOSUBj I statement label 


} 


IL = IBM-Labelled Tapes 
NL = Non-Labelled Tapes 
AL = ANSI-Labelled Tapes 


SELECT file specifies the characteristics of a file that is to be 
opened (see the OPEN statement in this section) and read from and/or 
written to (see READ, WRITE, REWRITE, GET, PUT, DELETE, and SKIP 
statements in this section). 
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SELECT can specify four types of files: 


1. Consecutive disk files — Files that can only be read or written 
to sequentially. You can use READ, WRITE, REWRITE, GET, PUT, and 
SKIP. 

2. Indexed disk files — Files indexed with a key field. You must 
specify the key length and position. Alternate keys can also be 
specified. Records can be accessed sequentially or by a specific 
key. You can use READ, WRITE, REWRITE, GET, PUT, DELETE, and SKIP. 

3. Tape — Files can be read from or written to a tape. You can use 
READ, WRITE, GET, PUT, and SKIP. 

4. Printer — Files can be v/ritten for output to the printer. The 
first two bytes in each record must be printer control characters 
(see the VS Principles of Operation ). Only WRITE and PUT can be 
used, and only Output mode can be used in the OPEN statement. 

The SELECT statement sets up a user file block (UFB) of file 
information and a record area for the specified consecutive, indexed, 
tape, or printer file, referenced by the file number, with the 
supplied parameters used to set initial values in the UFB. 

A file number cannot appear in more than one SELECT statement. All 
SELECT statements must appear before any file I/O statements in the 
program. 

SELECT statement parameters are described as follows. 

• file-number — Pound-sign (#) followed by an integer from 1 to 64, 
inclusive. This file number is used in all other I/O statements to 
refer to the file specified by this SELECT statement. 

• prname — Literal string consisting of 1 to 8 alphabetic or numeric 
characters, including $, #, and @. This is the external name used 
by the operating system to access the file and to prompt the user 
for file information. 

• VAR[C] — Variable-length [optionally compressed] records. Neither 
VAR nor C need be set for any existing file, but they must be set 
for a file to be created (Output mode) with variable-length (or 
compressed) records. 

• RECSIZE — Record size for fixed-length files; maximum record size 
for variable-length files. 
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Limits: 


CONSEC — 1 <= inti <= 2048 
VAR CONSEC — 1 <= inti <= 2024 
INDEXED — 1 <= inti <= 2040 
VAR INDEXED — 1 <= inti <= 2024 

• KEYPOS — Key position in record (from 1) for indexed files. 

• KEYLEN — Key length (maximum = 255) for indexed files. 

• lOERR — Branch taken if I/O error occurs on the selected file. 

• EOD — Branch taken if end-of-data, invalid key, or duplicate key on 
an I/O operation not having an EOD exit of its own. 

• ALTERNATE KEY, KEYPOS, KEYLEN, PUP (Duplicate Key values allowed) ~ 
Key number, position, and length for one alternate key. This 
applies to indexed files that allow up to 16 alternate key access 
paths. For an existing file, the ALTERNATE key list either can be 
omitted or a subset of the existing alternate key structure. The 
key numbers specified must be identical to those used when creating 
the file. Alternate keys that are not included are not accessible 
by either READ or the KEY() function. 

Syntax Examples : 

100 SELECT #1,'‘HEAP",VAR,CONSEC,RECSIZE = 100,EOD GOTO 1000 ! 

200 lOERR GOSUB 200 

300 SELECT#2,"OF",CONSEC,RECSIZE = 50 

400 SELECT#3,"BROKEN",INDEXED,RECSIZE = 200,KEYPOS = 1,KEYLEN = ! 

500 10,ALT KEY 1,KEYPOS = 11,KEYLEN = 10,KEY 2,KEYPOS = 21,KEYLEN = 10 

600 SELECT#4"IMAGES",VAR,TAPE,NL,RECSIZE = 15, BLKSIZE = 1000 ! 

700 DENSITY = 1600,EOD GOSUB 1000 

800 SELECT#5,"WHERE",PRINTER,RECSIZE = 134 
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SGN Function 


General Format: 
SGN (numeric exp) 


The SGN function returns an integer value equal to -1 if the argument 
is less than zero, 0 if the argument equals zero, or +1 if the 
argiament is greater than zero. 

Syntax Examples ; 

100 Y = SGN{X) 

200 Z = SGN(-5) 

Numeric Examples : 

SGN(5) = 1 
SGN{-5) = -1 
SGN(O) = 0 
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SIN Function 




General Format: 
SIN (numeric exp) 


The SIN function returns a floating-point value that is the sine of 
the numeric expression specified as its argument. The expression is 
calculated in units of radians, degrees, or grads, depending on the 
trigonometric mode specified by the most recently executed SELECT 
statement. If no SELECT statement was executed in the program or 
subprogram, the default mode is radians. 

Syntax Example : 

100 Y = SIN(X) 

Numeric Example : 

SIN(O) = 0 

SIN(90) = 1 (assuming the calculation is performed in degrees) 
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SIZE Function 


General Format: 
SIZE (file-exp) 


SIZE returns the size in bytes of the last record read from the 
specified file. The result is an integer. 


Syntax Example ; 

100 Y = SIZE(#1) 
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SKIP Statement 




General Format; 


SKIP file-exp [.EOD 

f line number 1 
y statement label j 

where: 


num-exp = number of records to skip; forward if n > 0; backward if n < 0 

BEG = skip to beginning of file 



The SKIP statement positions a CONSEC file forward or backward a given 
number of records, or to the beginning (BEG) of the file. The EOD 
exit is taken if a SKIP results in a position before the beginning or 
past the end of the file. For example, if record 1 was just read, 
SKIP#n,2 causes the next record read to be record 4. SKIP #n,-l 
causes the same record to be reread by the next READ or GET 
statement. A SKIP value of 0 is ignored. 

Syntax Examples ; 

100 SKIP #A,BEG 

200 SKIP #l,B,EOD GOTO 1000 
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SQR Function 




General Format: 
SQR (numeric exp) 


The SQR function returns a floating-point value that is the square 
root of the numeric expression specified as its argument. 

The numeric expression must be a positive number. 

Syntax Example : 

100 Y = SQR<X) 

Numeric Example : 

SQR(4) = 2 
SQR(16) = 4 
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STOP Statement 


General Format: 
STOP (alpha-exp] 


The STOP statement interrupts program execution. When STOP is 
encountered, STOP and the given alpha expression are printed at the 
workstation. 

When the compiler option MINANS = NO is selected, program execution 
can be continued. Execution can be continued in either of two ways: 

1. ENTER continues execution at the next executable statement 
following the STOP statement. 

2. Pressing a PF key corresponding to a marked subroutine causes the 
program to continue at the entry point of the subroutine. A 
corresponding RETURN causes the STOP to execute again. 

The execution of STOP is exactly like that of INPUT with no arguments 
in that the program waits for your response. This applies to using 
PF keys for DEFFN' strings and subroutine entry. Although data cannot 
be entered directly into a variable from STOP, data can be passed to 
the arguments of a DEFFN' subroutine. 

When the compiler option MINANS = YES is selected, execution of the 
program is interrupted and the program waits for either the ENTER key 
or a function key to be pressed. When this occurs, the program is 
terminated. Special PF key processing similar to that of the INPUT 
statement is ignored. 

Syntax Examples : 

100 STOP 
200 STOP A$ 

300 STOP "TWAS BRILLIG AND THE SLITHEY TOVES" 
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STR Fiinction 


General Format: 

STR(.. \ LblLLnlll) 

I alpha array string j 

where: 

s = starting character in substring (an expression) (1 if omitted); cannot be zero or 
negative 

n = number of consecutive characters desired (an expression); cannot be zero or 
negative 


The string function, STR, specifies a substring of an alpha variable 
or array string. With it, a portion of an alpha value can be 
examined, extracted, or changed. For example, the statement 

100 B$ = STR(A$,3,4), 

sets the receiver B$ equal to the third, fourth, fifth, and sixth 
characters of A$. 

If n is omitted, the remainder of the alpha value is used, including 
trailing spaces. 

Any attempt to create a substring of length zero results in a runtime 
cancel message. 

You can use the STR function as a receiver on the left side of an 
assignment (LET) statement to assign a value to a substring. 

Example : 

100 A$ = "ABCDEF" 

200 STR{A$,4,3) = "XYZ" 

300 PRINT A$ 

Output: 

ABCXYZ 

If the STR function is used on the left side of an assignment (LET) 
statement, and the value to be received is shorter than the specified 
substring, the substring is filled with trailing spaces. In this 
case, the first argument of the STR function must be an alpha receiver. 
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SUB Statement 


General Format: 

SUB "name" [ [ADDR](arg[,arg]...)] 


statements in subroutine 


where: 

"name" = name of subroutine (1 to 8 alphabetic or numeric characters; first alphabetic, 
including and $) 


arg = 


f alpha scalar variable 
1 numeric scalar variable 
j array-designator 
(^file-number 


The SUB statement defines a subroutine with {or without) an argument 
list. (Section 6.5 discusses the SUB statement and use of external 
subroutines.) Its logical end is signalled by an END statement, just 
as in a main program. The optional return code is ignored by the 
BASIC calling program. SUB must be the first statement, other than 
REM, in the program. 

The name specified in the SUB statement need not be the same as the 
object file name. Subroutines must be linked to their calling program 
prior to runtime. A CALL statement in the calling program initiates a 
branch to the beginning of the subprogram. 

The optional ADDR syntax specifies the type of address list that the 
SUB routine expects to be passed to it to locate the passed 
arguments. Refer to Section 6.5.4 for more information. 

Generally, when dealing entirely with VS BASIC programs and 
subprograms, do not use ADDR. Use ADDR only if the VS BASIC 
subroutine is being called from a non-BASIC (e.g., COBOL) subroutine. 

Variables and arrays local to the subroutine (i.e., not in the 
argument list) obey the usual rules. However, they are initialized 
only on the first subroutine call; on subsequent calls, they retain 
their previous values and dimensions. 
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The file number argument, used in file I/O statements, is logically 
replaced by the passed file number or file-expression when CALL is 
executed. The file number refers to SELECT and other I/O operations 
executed in the main program. Dummy file numbers cannot, therefore, 
appear in SELECT statements in the subroutine. When a file number is 
received as a parameter, a SELECT statement for that file number in 
the subroutine is not permitted. However, local file numbers can be 
used to set up (SELECT) an I/O area local to the subroutine, 
independent of and inaccessible to the calling program. 

Other arguments are passed as follows: 

1. Non-ADDR Form — The type (matrix, vector) of all array arguments 
must be specified for correct argument passing to occur. This can 
be done in either of tv/o ways: 

a. In one or more DIM statements occurring before the use of any 
of the dummy arrays. The dimensions specified are of no 
significance; the program notes only the vector-matrix 
distinction. 

b. If not in a DIM statement, the array is assumed to be a matrix. 

Arrays and receivers are not physically moved. The subroutine 
receives pointers to their locations and dimensions. Thus, 
changed values and array dimensions (MAT REDIM) can be returned to 
the calling program. 

Expressions and alpha expressions that are not receivers must be 
created in temporary locations by the calling program; otherwise, 
pointers to their locations (and lengths, for alpha expressions) 
are passed to the subroutine as in (a). Although values may be 
changed in the subroutine, the calling program does not have 
access to the new values. 

In either case, the defined dimensions and lengths received by the 
sijbroutine specify the maximum area, as in a DIM or COM 
statement. MAT REDIM can change these dimensions (subject to the 
usual rules) and, as indicated, these new dimensions are retained 
upon return to the calling program. 

2. ADDR Form — SUB passes pointers to the locations of the passed 
arguments. All array dimensions and alphanumeric lengths are as 
specified in the SUB program (or are the default values). 

Otherwise, the ADDR form is the same as the non-ADDR form. 
Specifically, any changes to the data are reflected in the calling 
program upon return from the siibroutine. MAT REDIM has no effect 
outside the subroutine, however, because the dimensioning 
information from the calling program is inaccessible to the called 
subprogram. 
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No subroutine dunany argument can have the same name as another dummy 
argument of the same type <scalar/array), or as a COM argument 
specified in the subroutine. 

A suUsroutine can call other subroutines, but cannot call itself. 

A source file can contain exactly one module, which can be either a 
program or a subroutine. 

Examples : 

100 SUB "AND" 

200 A$ = STRC'THE DRY STONE NO",5,3) 

300 PRINT A$' "SOUND OF WATER" 

400 END 

100 SUB "ONLY" ADDR{A$,B,BC( ),,#N) 

200 IF A$ AND "THERE IS A SHADOW" THEN B = 20 
300 END 

100 SUB "123456" (A$) 

100 PRINT A$ 

300 END 
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TAN Function 


General Format: 
TAN (numeric exp) 


The TAN function returns a floating-point value that is the tangent of 
the numeric expression specified as its argument. The expression is 
in units of radians, degrees, or grads, depending on the trigonometric 
mode specified by the most recently executed SELECT statement. If no 
SELECT statement was executed in the program or subprogram, the 
default mode is radians. 

Syntax Example : 

100 X = TAN(Y) 

Numeric Examples : 

TAN(O) = 0 

TAN(45) = 1 (assuming the calculation is performed in degrees) 
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TIME Function 




General Format: 
TIME 


TIME returns an 8-character string containing the current time 
(accurate to hundredths of a second) in the form HHMMSShh. 

Syntax Example : 

100 A$ = TIME 
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TITLE Compiler Directive 




General Format: 
TITLE [exp] 


The TITLE statement is a compiler directive (refer to Section 2.4.2). 

A TITLE statement must be the only statement on a line. When a TITLE 
statement is encountered during compilation, the compiler skips to the 
top of the next page of output listing and prints the expression in 
the TITLE statement. The same title appears on all subsequent pages 
of the listing until another TITLE statement occurs in the program 
text. 

TITLE statements cannot be continued, nor can they be used in a 
multiple statement line. 

Example : 

100 TITLE PART I: VARIABLE INITIALIZATION SECTION 
When this statement is encountered, the title 


PART I: VARIABLE INITIALIZATION SECTION 
appears at the top of the page of source listing. 
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TRAN Statement 


General Format: 

TRAN (alpha-receiver, alpha-exp) [REPLACING] 


TRAN translates (in place) the alpha receiver, using the alpha 
expression as a translate table or list. 

The defined length of the alpha receiver is translated left to right, 
one byte at a time, as follows: 

1. The alpha-expression (translate table) is moved to a separate 
location; thus, it cannot be affected by the translation. 

2. Each byte is translated in one of the following ways: 

a. REPLACING specified: The alpha expression is treated as a list 
of consecutive byte pairs, ending either at a HEX(2020) pair or 
at the end (last full byte pair) of the alpha-expression. The 
second byte of each pair is a "translate from" byte, and the 
first is a "translate to" byte. 

The alpha expression is searched from left to right until a 
"translate from" matching the subject byte is found. The 
sxabject byte is then changed to the corresponding "translate 
to" character. If a matching byte is not found, the subject 
byte is not changed. 

b. REPLACING not specified: The alpha expression is treated as a 
table of consecutive "translate to" bytes. The subject byte is 
changed to the (n+l)th byte in the table, where n is the hex 
value of the subject byte. If the alpha-expression has fewer 
than n+1 bytes, the subject byte is not changed. 

Example : 

100 A$ = "JOHN" 

200 6$ = HEX(00010203) 

300 TRAN(A$,"MJAORHYN")REPLACING 
400 TRAN(B$,"ABCDEF") 

500 PRINT A$,B$ 

Output: 

MARY ABCD 
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UNPACK Statement 


General Format: 


UNPACK PIC (image) alpha-expression TO 


{ numeric array-designator 
numeric variable 



numeric array-designator 
numeric variable 



where: 

image = [±][#.. .][.][#.. .][| H f Hat least 1 #} 


Use the UNPACK statement to unpack numeric data that was packed by a 
PACK statement. Starting at the beginning of the specified 
alphanumeric expression, packed numeric data is unpacked, converted to 
internal floating-point values, and stored into the specified numeric 
variables or arrays. The format of the packed data is specified by 
the image (see the PACK statement in this section); thus, the same 
image used to pack the data should be used in the UNPACK statement. 

An error results if the UNPACK statement attempts to unpack more 
numeric values than can exist in the alphanumeric expression (defined 
length used). 

Syntax Examples ; 

100 UNPACK PIC (####)A$ TO X,Y,Z 
200 UNPACK PIC (+#.##)STR(A$,4,2) TO X 
300 UNPACK PIC (+#.## )A$() TO N() 

400 UNPACK PIC (######)A$() TO X,Y,N(),M() 

Example : 

100 X = 24:DIM A$3 

200 PACK PIC (####)A$ FROM X 

300 PRINT X 

400 PRINT HEXOF (A$) 

500 UNPACK PIC (####)A$ TO Y 
600 PRINT A$,Y 

Output: 

24 

002420 

$ 24 
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$UMPACK Statement 






General Formats: 


$PACK 



alpha-exp) 


alpha-receiver FROM arg[,arg]... 


.DATA 


/goto \ / 

|GOSUBj I 


line number 
statement label 


} 


where: 


{ line number 
statement label 


line number or statement label of 
data conversion error exit 


fexp 

arg= < alpha-exp, EXCEPT alpha array string 
(^array-designator 


$UNPACK 


{?:} 


alpha-exp) 


alpha-exp TO arg[,arg]. 


.DATA 


/goto \ / line number 
^GOSUB j I statement label 


} 


where: 

_ /receiver, EXCEPT alpha array string! 
i array-designator j 


See the $PACK statement in this section for an explanation of the 
syntax. 




VS BASIC Statements and Functions 11-177 




VAL Function 




General Format: 

\/AL(alpha-exp[.dl) 

where: 

d = 1,2,3.4 (default = 1) 


The VAL function is the inverse of the BIN function. It converts the 
first d characters of the specified alphanumeric value to an integer. 
VAL can be used wherever numeric functions are used normally. (Refer 
to Section 5.6.4 for more information.) 

VAL is particularly useful for code conversion and table lookups, 
because you can use the converted number as a subscript to retrieve 
the corresponding code or data from an array, or to retrieve codes or 
information from DATA statements. 

Syntax Examples ; 




100 X = VAL{A$) 

200 PRINT VAL("A") 

300 IF VAL(STR(A$,3,1) 80 THEN 100 
400 Z = VAL(A$)*10-Y 
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WRITE Statement 


General Format: 

WRITE file-exp[USIZE=exp][L] MASK = alpha-expl ] 


[1 




l|j .arg[,{ 


pnr^ /goto \ /line number \ 

' ^ ' nr\ci it^r "S statement label/ 


^GOSUB/ '/statement 


/goto \ / line number 

'/ l 


DATA > 7 

,uMia Sqosub/ /Statement 


label 


} 


where: 

SIZE = record size for VAR files. 

MASK = 2-byte mask alternate index mask for alternate indexed 
files. (If only 1 byte, right-padded with HEX (00)) 


f line number 


USING ^ III ic I lui I luci l _ line number of Image or FMT 

1 statement label / describing formatting to be used 


on the output data 


If USING is omitted, internal format Is used. 

fexp ] 

arg = < alpha-exp > 

[ array-designator J 


EOD = duplicate-key exit; overrides the SELECT EOD 
DATA = data conversion error exit (formatting error) 


WRITE writes the next sequential record to a CONSEC file (Output, 
Extend, or Shared mode), or a keyed record to an INDEXED file (I/O, 
Output, or Shared mode). Section 8.4 discusses the WRITE statement in 
more detail. 

If an argument list is present, the data is moved one value at a time, 
using the format specified by Image (%), FMT, or internal formatting. 
If an argument list is not present, the data is taken directly from 
the record area, where it was already formatted with a PUT statement. 

Direct concatenation operations within the WRITE statement are illegal 
in VS BASIC. 

For non-VAR[C] files, the record size is as specified in SELECT; the 
SIZE parameter is ignored. For VAR[C] files, the record size is 
determined in one of the following ways: 
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1. Record size equals the SIZE expression, if specified. 

2. If an argument list is present, record size equals the resulting 
formatted record size. If USING is omitted, the data is left in 
the internal format, with the record size equal to the sum of 
individual sizes: 

floating-point = 8 bytes 
integer = 4 bytes 

alphanumeric = defined length 

3. If no argument list is present, then the record size is identical 
to that of the last record read or written, if any, or to the 
maximum RECSIZE. 

For alternate indexed files, MASK is used to set the alternate key 
mask for the record (refer to the description of the MASK function in 
Section 8.5.3). If omitted, the current MASK is used. 

Syntax Example : 

100 WRITE #N,SIZE = 100,MASK = A$,E0D GOTO 1000,DATA GOTO 1200 
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XOR Statement 






General Format: 

[LET] alpha-receiver = [logical exp] XOR logical exp 
logical exp: see Section 5.7 


The XOR operator perforins a logical exclusive OR on two or more 
alphanumeric arguments. 

If the operand (logical expression) is shorter than the receiver, the 
remaining characters of the receiver are left unchanged. If the 
operand is longer than the receiver, the operation stops v/hen the 
receiver is filled. (Refer to Section 5.7 for more information on 
logical expressions.) 

Syntax Example : 

100 Y$ = HEX(OO) XOR HEX(AA) 

Numeric Examples ; 

HEX(OOOO) = HEX(OFOF) XOR HEX(OFOF) 

HEX(OFFO) = HEX(OOFF) XOR HEX(OFOF) 
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Appendixes 




APPENDIX A 

VS BASIC RESERVED WORDS 


This appendix contains a list of all VS BASIC reserved words. 

Reserved words have a specific meaning to the VS BASIC compiler as 
statement verbs and keywords, and cannot be used either as variable 
names or as statement labels. Some words on this list are not 
documented in this manual, since they are reserved for features to be 
implemented in future versions of the VS BASIC compiler. 






ABS 

ACCEPT 

ADD 

ADDC 

ADDR 

AL 

ALL 

ALT 

ALTERNATE 

AND 

ANY 

ARCCOS 

ARCSIN 

ARCTAN 

ASORT 

AT 

ATN 

BASE 

BEG 

BELL 

BI 

BIN 

BLANK 

BLINK 

BLKSIZE 

BLOCKS 

BOOL 

BOOLO 

BOOLl 

BOOL2 

B00L3 

BOOL4 

BOOLS 

B00L6 

BOOL7 

BOOLS 

B00L9 

BOOLA 

BOOLB 

BOOLC 

BOOLD 

BOOLE 

BOOLF 

BRIGHT 

BY 

CALL 

CH 

CHAR 

CLEAR 

CLOSE 

COL 

COM 

COMMON 

CON 

CONSEC 

CONSTANT 

CONVERT 

COPY 

COS 

CRT 

CURSOR 

DATA 

DATE 

DECIMAL 

DEF 

DEFAULT 

DEF FN 

DEF FN' 

DEGREES 

DELETE 

DENSITY 

DIM 

DISPLAY 

DO 

DPACK 

DSORT 

DUP 

EJECT 

ELSE 

END 

ENTER 

EOD 

ERROR 

EXP 

EXTEND 

FAC 

FILE 

FILESEQ 

FILL 

FL 

FLOAT 

FMT 

FN 

FN' 

FOR 

FORM 

FR 

FROM 

FS 

GET 

GO 

GOSUB 

GOSUB’ 

GOTO 

GRADS 

HALT 

HEX 

HEXOF 

HEXPACK 

HEXPRINT 

HEXUNPACK 

HOLD 
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IDN 

IP 

IL 

INDEXED 

INIT 

INPUT 

INT 

INTEGER 

INTO 

INV 

10 

lOERR 

IPACK 

KEY 

KEYLEN 

KEYPOS 

KEYS 

LEN 

LET 

LGT 

LIBRARY 

LINE 

LOG 

LONG 

MASK 

MAT 

MAX 

MIN 

MOD 

NEC 

NEXT 

NL 

NOALT 

NODISPLAY 

NOGETPARM 

NOT 

NUM 

OBJECT 

ON 

ONLY 

OPEN 

OPTION 

OR 

OUTPUT 

PACK 

PAGE 

PAUSE 

PD 

PI 

PIC 

POOL 

POS 

PRINT 

PRINTER 

PROTECT 

PUT 

RADIANS 

RANSOMIZE 

RANGE 

READ 

REAL 

RECORD 

RECSIZE 

REDIM 

REM 

REMARK 

REPEAT 

REPLACING 

RESTORE 

RETURN 

REWRITE 

RND 

ROTATE 

ROTATEC 

ROUND 

SCREEN 

SEARCH 

SELECT 

SGN 

SHARED 

SHORT 

SIN 

SIZE 

SKIP 

SOURCE 

SPACE 

SQR 

STEP 

STOP 

STR 

SUB 

SUB' 

TAB 

TABLE 

TAN 

TAPE 

THEN 

TIME 

TIMEOUT 

TITLE 

TO 

TRACE 

TRAN 

TRN 

UNDERLINE 

UNPACK 

UPPERCASE 

USING 

VAL 

VALIDATE 

VALUE 

VAR 

VARC 

VOLUME 

WINDOW 

WRITE 

ws 

XOR 

XX 

ZD 

ZER 

ZERO 



$PACK 

$UNPACK 






o 
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APPENDIX B 

VS BASIC COMPILER OPTIONS 


The VS BASIC compiler provides the following options: 


SOURCE 

If SOURCE = YES, the compiler produces a source listing of the 
compiled program, with accompanying diagnostics. If SOURCE = NO, the 
compiler does not produce a source listing. (Diagnostics are produced 
if either SOURCE, PMAP, XREF, or ERRLIST is specified.) 


PMAP 


If PMAP = YES, the compiler produces a PMAP (program map) for the 
compiled program. A PMAP contains the machine instructions generated 
by each VS BASIC verb, with the address of each instruction, as well 
as a map of the static area showing the values and locations of all 
data items. A PMAP consists of five basic columns: 

1. Column 1 - VS BASIC verbs and line numbers 

2. Column 2 - Address and object code 

3. Column 3 - Assembler instructions 

4. Column 4 - Operands for instructions, hex codes for literals 

5. Column 5 - Comments 

If the program contains common variables (i.e., listed in a COM 
statement), a map of the common area follows the PMAP, beginning with 
^COMMON on a new page. In the common area map, the columns serve the 
same purpose as in the PMAP, except for the first column. The first 
column of the common area map contains only *COMMON at the beginning 
of the map. If there is no common area, a map of the static area 
immediately follows the PMAP, beginning with the word STATIC in 
column 1 on a new page. 
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In the static area map, the columns serve the same purpose as in the 
PMAP, with the exception of the first column. The first column 
contains either *STATIC, indicating the address of the contents of the 
next static section, or *PGT (Program Global Table) indicating the 
address of the information in the next table. The static section 
contains variables, while the PGT contains such data items as 
subroutine addresses and other constants. 


XREF 


The XREF (cross-reference) listing consists of five parts; 

1. A listing of line number references (column one) and the line 
numbers that reference them (following columns). 

2. A listing of the variable names, their lengths (alpha only), and, 
for arrays, their dimensions (all in column one). Each variable 
is followed by the location of the variable's storage area (or, 
for arrays, the descriptor and data area) on the same line, and 
the line numbers that reference the variable (on succeeding lines). 

3. A listing of user-defined functions and the line numbers that 
reference them. 

4. A listing of VS BASIC functions referenced, and the line numbers 
that reference them. 

5. A listing of DEF FN' subroutines contained within the program and 
the line numbers that reference them. 


LOAD 

If LOAD = YES, the compiler creates an object program in VS object 
program format, and stores it in an output file. If LOAD = NO, the 
compiler does not create an object program and does not display an 
output definition screen to name the output file. 


SYMB 

If SYMB = YES, the compiler inserts symbolic debug information in the 
object program. If SYMB = NO, the compiler does not insert this 
information, and the symbolic debug facility cannot be used to debug 
the object program at runtime. 
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SUBCHK 


If SUBCHK = YES, the compiler generates special code that checks the 
ranges of subscripts during program execution, and causes a program 
cancellation (execution interruption) if a subscript exceeds its 
defined limit. Otherwise, no check is performed on subscripts during 
execution. 


DFLOAT 

If DFLOAT = YES, the compiler uses the float decimal representation 
for all floating-point operations in this module. Since float decimal 
support is not available on VS80 and VS50 systems, a response of YES 
on VS80 and VS50 systems generates an immediate error message. The 
default response, NO, instructs the compiler to the float binary 
representation for all floating-point operation in this module. 


ERRLIST 

If ERRLIST = YES, a listing of the compiler diagnostics is produced. 


FLAG 


The FLAG option specifies the lowest level of error severity that 
causes the compiler to print a diagnostic message. Any error with a 
severity code greater than or equal to the specified FLAG value causes 
the compiler to print a diagnostic message. 


STOP 


The STOP option specifies the lowest level of error severity that 
causes the compiler to abort the compilation. Any error with a 
severity code greater than or equal to the specified STOP value 
terminates the compilation (no object program is produced). 


LINES 


The LINES option sets the number of lines per page for all 
compiler-produced printouts. 


MINANS 

The MINANS option specifies that Minimal ANSI rules are applied before 
processing the program. When MINANS = YES, RANDOMIZE and OPTION BASE 
are available. Setting MINANS = YES forces SUBCHK and DFLOAT to YES. 
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APPENDIX C 

FLOATING-POINT AND INTEGER CALCULATIONS 


C.l INTRODUCTION 

VS BASIC supports two numeric formats: integer and floating-point. In 
addition, you can choose one of two floating-point representations: 
float binary or float decimal. Each format has unique features and 
limitations that make it suitable for some applications and 
unsuitable for others. Chapter 3 compared the speed and precision of 
the numeric formats in a general sense. This appendix provides a more 
detailed description of the advantages and disadvantages of each 
format. 


C.2 INTEGER FORMAT 

Integer calculations are precise and consistent for a limited range of 
values. On the VS, the range is from -2,147,483,648 to 
2,147,483,647. Except for the occurrence of integer overflow, 
standard integer operations (including arithmetic and relational 
operators) produce the expected results and obey standard mathematical 
laws, such as those concerning associative and commutative 
operations. For example, integer equality (’'=”) tests for exact 
equality, and it is easy to understand when two integers are exactly 
equal. 

Use integer variables whenever precise results are required and the 
expected range of values falls within the limited range supported by 
VS BASIC. 


C.3 FLOAT BINARY FORMAT 


The float binary format can represent the largest range of values 
(+ 5.4 X 10“^^ to + 7.2 X 10^^) of all numeric formats. Float 
binary calculations are slower than integer calculations, but are 
faster than those performed in float decimal. Float binary 
operations, however, are the least precise of operations on the 
numeric data types. 
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Float binary operations lose precision when the internal hexadecimal 
representation (refer to Chapter 3) is converted to or from the 
decimal representation. The conversion can result in a loss of 
precision because a one-to-one correspondence does not exist between 
hexadecimal and decimal fractions. For example, the decimal fraction 
0.2 converts to a repeating hexadecimal fraction of 0.33333... The 
float binary format cannot exactly represent decimal 0.2 in a finite 
number of digits. Operations on the exact decimal value 0.2 
manipulate the hexadecimal approximation 0.33333333333333 rather than 


0.333... 


In most cases, the loss of precision in a 14-digit floating-point 
value is not significant. The VS BASIC input/output routines (PRINT, 
ACCEPT, INPUT, etc.) automatically perform the interconversions of 
numeric data between the decimal form shown in ASCII characters on the 
workstation or printer and the internal hexadecimal form. The loss of 
precision can become significant, however, when an iterative series of 
calculations is performed, or when the value is compared to an exact 
value. 

Conversion errors in iterative calculations can accumulate over a 
series of calculations to such an extent that they affect the end 
result. For example, though the arcsine of the sine of 90 degrees is 
90 degrees, the program 

100 SELECT DEGREES /* Set the TRIG mode to DEGREES */ 

200 PRINT ARCSIN(SIN(90)) 

displays 89.9999994771725 rather than 90. If the result of the ARCSIN 
function were used directly in subsequent calculations, the final 
results of the calculations would be slightly inaccurate. If further 
conversion errors occurred in these calculations, the end result could 
be significantly inaccurate. 

Conversion errors can also significantly influence the result of a 
comparison operation. When two float binary values are compared, the 
comparison is performed on their hexadecimal values. For example, the 
statement IF A = B THEN PRINT C compares the contents (in hexadecimal) 
of A and B; if the two values are not exactly equal, the comparison 
fails. Consider, for example, the following short program: 

100 A = 12 

200 B = (12 / 10) * 10 

300 PRINT "A = "; A; "B = B; "THEY ARE"; 

400 IF A = B THEN PRINT "EQUAL" ELSE PRINT "NOT EQUAL" 

Result: 

A = 12 B = 12 THEY ARE NOT EQUAL 
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This apparently anomalous result illustrates how a loss of precision 
that has no noticeable effect on the result of the computation can 
influence the results of other operations. In this case, the division 
on line 200 produces a result, 1.2, that is normal in decimal but is a 
repeating fraction in hexadecimal (because, as noted above, the 
fraction of 0.2 does not have an exact hexadecimal equivalent). When 
the quotient is multiplied by 10, the result in B is not exactly the 
hexadecimal equivalent of 12, but is instead a very close 
approximation. 

Since the comparison at line 400 expects the values of A and B to be 
exactly equal, the condition is not met, and the ELSE statement is 
executed. However, because formatted output statements in VS BASIC 
(such as the PRINT at line 300) perform an implicit rounding of the 
result that compensates for the one-bit loss of precision, both A and 
B print as 12. 

For most applications, the loss of precision suffered by float binary 
operations is insignificant and is not a cause of concern to you. In 
those cases where it is a problem, several courses of action are 
available. 

The float decimal representation (refer to Section C.4 and Chapter 3) 
performs floating-point operations with no loss of precision. If 
float decimal is not supported on your VS system or is inappropriate 
due to other considerations, the ROUND function can in some cases 
reduce the problems associated with the float binary representation. 
However, since the definition of rounding (i.e., increase if the digit 
is greater than or equal to 5) is based on the assumption of a decimal 
number system, ROUND can also produce unexpected results when the 
digit being rounded is very close to but slightly less than 5. This 
is again due to the fact that the float binary number is an 
approximation of the decimal number. For example, consider the 
following program: 

100 C = 30.5 * 11.69 

200 D = ROUND (C,2) 

300 PRINT "C =": C, "D = •'; D 

Result: 

C = 356.545 D = 356.54 

The expected result in D is 356.55. 


Floating-Point and Integer Calculations C-3 



For applications in which it is not feasible to use integer or float 
decimal arithmetic, consider using a PL/I or COBOL subroutine to 
perform the necessary calculations. PL/I and COBOL support packed 
decimal format, a data format not available in VS BASIC. With packed 
decimal format, arithmetic operations are performed directly in 
decimal, with no conversion to binary. Thus, any loss of precision 
due to conversion from decimal to binary {or to hexadecimal) is 
avoided. See the VS COBOL Reference and the VS PL/I Language 
Reference for a discussion of the COBOL and PL/I languages and the 
data formats available. 


C.4 FLOAT DECIMAL FORMAT 


The range of values for which float decimal calculations are precise 
and consistent is larger than for the integer format, but smaller than 
for the float binary format. On the VS, the range is from +1E-65 to 
+1E63. Standard floating-point operations, including arithmetic and 
relational operators, produce the expected results and obey standard 
mathematical laws, such as those concerning associative and 
commutative operations. For example, float decimal equality ("=") 
tests for exact equality, and it is easy to understand when two float 
decimal values are exactly equal. 

Float decimal calculations, however, are the slowest of all numeric 
operations. In addition, modules compiled with float decimal numerics 
are incompatible with modules compiled with float binary numerics; if 
two modules with different floating-point representations share 
floating-point data, the shared data must be converted with the CVDQ 
or CVQD subroutines described in Part II of this manual. The "Inspect 
and Modify" function of the Symbolic Debugger currently does not 
recognize float decimal data; however, the data can be examined in 
hexadecimal form. Consult the VS Principles of Operation for details 
on the hexadecimal format of float decimal data. 

Float decimal format is appropriate for those cases where precise 
results are required, the speed of the calculation is not important, 
and the program does not need debugging. The float binary 
representation is preferred in other cases because it is more 
transportable and faster, and it can represent a larger range of 
values. 


NOTE 


When the compiler option MINANS = YES is selected, all processing is 
float decimal. 
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APPENDIX D 

NUMERIC DATA FORMAT COMPATABILITY BETWEEN VS BASIC AND COBOL 


VS BASIC stores integer data as binary integers in four bytes of 
memory (one full word), float binary data as hexadecimal fractions in 
eight bytes, and float decimal data as decimal fractions in eight 
bytes. Other languages, however, may use other formats for storing 
numeric data. . In particular, COBOL stores integer data as half-word 
binary integers, and noninteger numeric data in packed decimal 
format. In packed decimal format, each decimal digit of a number is 
coded into four bits of storage. A hexadecimal digit attached to the 
right (low-order end) of the number indicates the sign. The decimal 
point is not stored; its position is specified only upon input or 
output. 

For most applications, the number representation schemes used by other 
languages are of no concern to you. If a VS BASIC program and a 
program written in COBOL are to process any of the same data, however, 
this difference cannot be ignored. This situation arises if a BASIC 
program and a COBOL program access the same data in either of the 
following ways: 

1. A VS BASIC program reads a data file written by a COBOL program, 
or vice versa. 

2. Argmnents are passed between a calling program and a subprogram 
when one program is in VS BASIC and the other is in COBOL. 

Numeric data to be transferred from a VS BASIC program to a COBOL 
program must first be converted to half-word integer or packed decimal 
format. Similarly, numeric data transferred from a COBOL program to a 
VS BASIC program must be converted from half-word integer or packed 
decimal to VS BASIC full-word integer or floating-point format before 
you can perform any numeric operations on them. 
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These conversions are most easily accomplished using the BI and PD 
data specification of the FMT statement. For example, to write the 
number 123.45 to a data file to be read later by a COBOL program, use 
the following program: 

2600 NUMBER = 123.45 

2700 WRITE #1, USING PACKED_DECIMAL, NUMBER 
2800 PACKED_DECIMAL: FMT PD(5,2) 

The following line reads a value from a data file that was written by 
a COBOL program: 

3300 READ #2, USING PACKED_^DECIMAL, VALUE 

Packed decimal numbers are stored as a series of decimal digits with 
no decimal point. When a packed decimal number is read from a file 
and converted to VS BASIC floating-point format, the value is 
converted to the type of floating-point format (float binary or float 
decimal) that is used in the module. The decimal point is inserted at 
the point indicated by the PD specification. As a result, the 
location of the "implied" decimal point must be known beforehand, so 
that the PD specification can be written appropriately. 

Numeric data passed between VS BASIC and COBOL calling programs and 
subprograms can be converted between full-word integer or 
floating-point and half-word integer or packed decimal formats using 
the PUT and GET statements, in conjunction with an FMT statement with 
a BI or PD specification. Half-word integer and packed decimal 
representations of numbers in VS BASIC must be stored in alpha- 
receivers. For example, a VS BASIC program can call a COBOL 
subroutine to perform some calculations using the integer variable 
OPTION^ and the floating-point variables RATE, TIME, and DISTANCE. 
Before the CALL statement, the data can be converted to the 
appropriate COBOL formats (one half-word integer, and three packed 
decimal numbers) by performing 

5600 PUT OPTION$, USING PD_F0RM1, OPTION^ 

5700 PUT RATE$, USING PD_F0RM2, RATE 
5800 PUT TIME$, USING PD_F0RM2, TIME 
5900 PUT DISTANCE$, USING PD_FORM2, DISTANCE 
6000 

6100 PD_F0RM1: FMT BI(2) 

6200 PD_F0RM2: FMT PD(6,2) 

6300 

6400 CALL ADDR SUB "CRUNCH" (OPTION$, RATE$, TIME$, DISTANCE$) 








D-2 Numeric Data Format Compatibility between VS BASIC and COBOL 



Although the arguments passed by the calling program are in a format 
designated by VS BASIC as an alphanumeric format, they correspond 
internally to COBOL's half-word integer and packed decimal numeric 
format. After the subprogram ends and control returns to the calling 
program, any changes made to the argument values by the COBOL 
subprograms can be retrieved and used as numeric values by the 
VS BASIC program with a conversion routine such as the following: 

6500 GET OPTION$, USING PD_F0RM1, OPTION^ 

6600 GET RATE$, USING PD_FORM2, RATE 

6700 GET TIME$, USING PD_F0RM2, TIME 

6800 GET DISTANCE$, USING PD_FORM2, DISTANCE 

The variables OPTIONS, RATE, TIME, and DISTANCE now reflect any 
changes made to these values by the COBOL subprogram. 

Similarly, if a COBOL program calls a VS BASIC subprogram, the numeric 
arguments from the COBOL program are passed to the VS BASIC subprogram 
as half-word integers and/or packed decimal numbers. Since only alpha 
receivers can receive these formats in VS BASIC, the parameters in the 
SUB statement of the VS BASIC subroutine must be alpha receivers. 
Before any numeric operations can be performed, the data must be 
converted (or unpacked) to VS BASIC integer and/or floating-point 
format(s). This is done using the GET statement (as above) and FMT 
statements with the appropriate BI and PD specifications. If the 
subroutine is to pass any numeric data back to the calling program, 
they must first be converted back to half-word integer or packed 
decimal format by PUT statements using the appropriate BI and PD 
specifications in one or more FMT statements. 
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VS Character Set E-1 














































































































































APPENDIX F 

VS FIELD ATTRIBUTE CHARACTERS 






Bright 

Modify 

All 

No line 

80 

Bright 

Modify 

Uppercase 

No line 

81 

Bright 

Modify 

Numeric 

No line 

82 

Bright 

Protect 

All 

No line 

84 

Bright 

Protect 

Uppercase 

No line 

85 

Bright 

Protect 

Numeric 

No line 

86 

Dim 

Modify 

All 

No line 

88 

Dim 

Modify 

Uppercase 

No line 

89 

Dim 

Modify 

Numeric 

No line 

8A 

Dim 

Protect 

All 

No line 

8C 

Dim 

Protect 

Uppercase 

No line 

8D 

Dim 

Protect 

Numeric 

No line 

8E 

Blink 

Modify 

All 

No line 

90 

Blink 

Modify 

Uppercase 

No line 

91 

Blink 

Modify 

Numeric 

No line 

92 

Blink 

Protect 

All 

No line 

94 

Blink 

Protect 

Uppercase 

No line 

95 

Blink 

Protect 

Numeric 

No line 

96 

Blank 

Modify 

All 

No line 

98 

Blank 

Modify 

Uppercase 

No line 

99 

Blank 

Modify 

Numeric 

No line 

9A 

Blank 

Protect 

Ail 

No line 

9C 

Blank 

Protect 

Uppercase 

No line 

9D 

Blank 

Protect 

Numeric 

No line 

9E 

Bright 

Modify 

All 

Line 

AO 

Bright 

Modify 

Uppercase 

Line 

A1 

Bright 

Modify 

Numeric 

Line 

A2 

Bright 

Protect 

All 

Line 

A4 

Bright 

Protect 

Uppercase 

Line 

A5 

Bright 

Protect 

Numeric 

Line 

A6 

Dim 

Modify 

All 

Line 

A8 

Dim 

Modify 

Uppercase 

Line 

A9 

Dim 

Modify 

Numeric 

Line 

AA 

Dim 

Protect 

All 

Line 

AC 

Dim 

Protect 

Uppercase 

Line 

AD 

Dim 

Protect 

Numeric 

Line 

AE 

Blink 

Modify 

All 

Line 

BO 

Blink 

Modify 

Uppercase 

Line 

B1 

Blink 

Modify 

Numeric 

Line 

B2 

Blink 

Protect 

All 

Line 

B4 

Blink 

Protect 

Uppercase 

Line 

B5 

Blink 

Protect 

Numeric 

Line 

B6 

Blank 

Modify 

All 

Line 

B8 

Blank 

Modify 

Uppercase 

Line 

B9 

Blank 

Modify 

Numeric 

Line 

BA 

Blank 

Protect 

All 

Line 

BC 

Blank 

Protect 

Uppercase 

Line 

BD 

Blank 

Protect 

Numeric 

Line 

BE 
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APPENDIX G 

ASCII COLLATING SEQUENCE 




Sequence Symbol 


Meaning 


1 

2 

3 $ 

4 

5 ( 

6 ) 

7 * 

8 + 

9 

10 
11 

12 / 

13-22 

23 ; 

24 < 

25 

26 > 


27-52 

53-78 


space 

quotation mark 
currency symbol 

apostrophe, single quotation mark 

left parenthesis 

right parenthesis 

asterisk 

plus symbol 

comma 

hyphen, minus symbol 
period, decimal point 
stroke, virgule, slash 
0 through 9 
semicolon 
less than 
equal sign 
greater than 
A through Z 
a through z 
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APPENDIX H 

VS BASIC ERROR MESSAGES 


The following list contains VS BASIC error messages in error-number 
order. VS BASIC error messages are designed to be self-explanatory 
and self-documenting. For more information regarding the cause or 
resolution of an error, see the section referenced next to the error 
message. Note that references to xxx and yyy in the list refer to 
elements of the message that are program-specific. 






Error 

Number 

Error Message 

Severity 
Return Code 

Section 

Reference 

101 

Line number in succeeding 
line is invalid. 

12 

2.3 

102 

Invalid character found. 

8 

Appendix E 

103 

Line number is out of 
sequence. 

8 

2.3 

104 

Literal not completed. 

8 

3.4 

105 

Literal improperly placed 
within statement. 

8 

2.3, 3.4 

106 

Incorrect constant or 
delimiter. 

8 

3.3 

107 

Constant improperly placed 
within statement. 

8 

2.3, 3.3 

108 

Line number is no followed 
by a space. 

8 

2.3 

109 

Invalid identifier name. 

8 

6.2 

110 

Constant too long - 
Significant digits lost. 

4 

3.3 


VS BASIC Error Messages H-1 



Error 

Niimber 

Error Message 

Severity 
Return Code 

Section 

Reference 


111 

Literal too long - Truncated 
to 256 characters. 

4 

3.4 


112 

A character string of length 
zero is invalid - Single blank 
substituted. 

4 

3.4 


113 

Improperly formed picture 
constant. 

8 

3.2 


114 

Numeric constant too large - 
Set to largest possible number. 

4 

3.3 


115 

Numeric constant too small - 
Set to zero. 

4 

3.3 


116 

HEX literal must contain an 
even number of characters. 

8 

3.4 


117 

Invalid Boolean function - 
must be 0-9 or A-F. 

8 

5.7 


118 

Invalid HEX literal. 

8 

3.4 


119 

Numeric constant too large 
for INTEGER - Treated as 

FLOATING POINT. 

8 

3.3 

120 

Last line of file contains a 
continuation character - your 
source file may be damaged. 

8 

2.3 


121 

Invalid exponent found in 
floating-point constant. 

8 

3.3 


122 

Variable name exceeds 64 
characters in length - 
Truncated. 

8 

3.2 


123 

Floating decimal numerics 
not available on this machine 
at this time. 

12 

N/A 


124 

Comment (PL/I style) 
unterminated at end of source 
file. 

8 

2.4 


H-2 VS BASIC 

Error Messages 







Error 

Number 

Error Message 

Severity 
Return Code 

Section 

Reference 


201 

Expecting end of statement but 
XXX was found. 

8 

2.3 


202 

Expecting line number or label 
but XXX was found. 

8 

6.3 


203 

Expecting statement verb but 
XXX was found. 

8 

2.3 


204 

Expecting yyy but xxx was 
found. 

8 

2.3 


205 

Expecting numeric or alpha 
expression but xxx was found. 

8 

4.3 


206 

Expecting alpha expression but 
xxx was found. 

8 

5.4 


207 

Expecting alpha receiver but 
xxx was found. 

8 

5.4 


208 

Expecting numeric scalar 
variable but xxx was found. 

8 

3.3, 3.5 


209 

Expecting alpha scalar 
variable but xxx was found. 

8 

3.4, 3.5 


210 

Expecting numeric array 
designator but xxx was found. 

8 

3.5 


211 

Expecting alpha array 
designator but xxx was found. 

8 

3.5 


212 

Expecting GOTO or GOSUB but 
xxx was found. 

8 

6.1, 6.4 


213 

Expecting matrix function or 
array variable but xxx was 
found. 

8 

9.2 


214 

Expecting matrix operator but 
xxx was found. 

8 

9.2 


215 

Expecting array variable but 
xxx was found. 

8 

3.5 
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Error 

Number 

Error Message 

Severity 
Return Code 

Section 

Reference 

216 

Expecting relational operator 
but XXX was found. 

8 

4.2, 5.2 

217 

Expecting numeric receiver or 
numeric array designator but 

XXX was found. 

8 

3.2, 3.5 

218 

Expecting numeric array but 

XXX was found. 

8 

3.5 

219 

Expecting alpha array but xxx 
was found. 

8 

3.5, 5.3 

220 

Expecting alpha array or alpha 
array designator but xxx was 
found. 

8 

3.5, 5.3 

221 

Expecting print delimiter but 
xxx was found. 

8 

7.2 

222 

Expecting 1, 2, 3, or 4 but 
xxx was found. 

8 

5.6 

223 

Expecting numeric array or 
numeric array designator but 
xxx was found. 

8 

3.5 

224 

Expecting numeric or alpha 
array designator but xxx was 
found. 

8 

3.5, 5.3 

225 

Expecting matrix variable or 
matrix function but xxx was 
found. 

8 

9.2 

226 

Expecting literal but xxx was 
found. 

8 

3.4 

227 

Expecting hexadecimal digit 
but xxx was found. 

8 

3.4 

228 

Expecting numeric constant or 
literal but xxx was found. 

8 

3.3, 3.4 

229 

Expecting numeric constant but 
xxx was found. 

8 

3.3 

230 

Expecting image but xxx was 
found. 

8 

7.4 
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Error 

Number Error Message 


Severity 
Return Code 


231 Expecting integer constant but 8 

XXX was found. 

232 Expecting array variable or 8 

alpha scalar but xxx was found. 

233 Expecting alpha scalar or 8 

alpha array designator but xxx 

was found. 

234 Expecting 1 or 2 but xxx was 8 

found. 

235 SUB statement may not be 8 

preceded by any statements 

other than comments. 

236 xxx has been previously 8 

defined. 

237 Line number does not precede 8 

xxx statement. 

238 Expecting GOTO or GOSUB but 8 

xxx was found. 

239 Invalid file niamber - Valid 8 

range is 1 to 64. 

240 Expecting prname literal but 8 

xxx was found. 

241 Expecting lOERR or EOD but 8 

xxx was found. 

242 Expecting DEGREES, GRADS, 8 


RADIANS, PAUSE, CRT, WS, 

POOL, PRINTER, or file 
expression but xxx was found. 

243 The SELECT statement must 8 

precede any disk Input/Output 
statements. 

244 Either equal sign is missing 8 

in a LET statement or this 
statement starts with an 
unrecognizable word. 


Section 

Reference 

3.3 

3.4, 3.5 

3.4, 3.5, 

5.3 

BIN entry; 
Part II 

6.5 

4.4 

2.3 

6.1, 6.4 

8.3 

8.3 

8.3 

8.3 

8.3 

2.3 
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Error 

NiJinber 

Error Message 

Severity 
Return Code 

Section 

Reference 


245 

Multiply defined parameter in 
OPEN statement. 

4 

8.3 


246 

Expecting DATA but xxx was 
found. 

8 

8.3 


247 

Expecting EOD but xxx was 
found. 

8 

8.3 


248 

Function previously defined. 

8 

4.4 


249 

Invalid number of arguments. 

8 

6.5 


250 

Expecting integer 0-255 but 
xxx was found. 

8 

8.3 


251 

Expecting a function but 
xxx was found. 

8 

4.4 


252 

Expecting OPEN mode indication 
(INPUT, OUTPUT, 10, SHARED, or 
EXTEND) but xxx was found. 

8 

8.3 


253 

Invalid argument type in SUB 
statement. 

8 

6.5 


254 

Expecting format statement 
specification but xxx was 
found. 

8 

7.4 


255 

Expecting file expression but 
xxx was found. 

8 

Chapter 8 


256 

Expecting error specification 
but xxx was found. 

8 

8.3 


257 

Expecting file number or 

BLOCKS but xxx was found. 

8 

8.3 


258 

Expecting comma or equal sign 
but xxx was found. 

8 

2.3 


259 

This statement too long. 

8 

2.2 


260 

Expecting keyword option but 
xxx was found. 

8 

8.3 


261 

Missing comma before xxx. 

6 

2.3 

o 
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Error 

Nijinber 

Error Messaqe 

Severity 
Return Code 

Section 

Reference 


262 

Expecting equal sign or 
parenthesis after yyy but xxx 
was found. 

8 

2.3 


263 

Expecting COMSEC or INDEXED 
but xxx was found. 

8 

8.3 


264 

Invalid use of xxx in ACCEPT 
statement. 

8 

7.5 


265 

Incorrect number of 
subscripts. 

8 

3.5 


266 

Length must be in range 1 
to 256. 

6 

8.3 


267 

xxx is not a valid name. 

4 

6.2 


268 

Invalid use of xxx in DISPLAY 
statement. 

8 

7.6 


269 

Nested IF statements are not 
allowed. 

8 

4.2, 5.2 


270 

xxx not yet implemented in 
ACCEPT or DISPLAY. 

8 

7.5, 7.6 


271 

xxx already specified in 
ACCEPT. 

8 

7.5 


272 

File was not previously 
specified in a SELECT 
statement. 

8 

8.3 


273 

Invalid device type for this 
function. 

8 

8.3 


274 

Invalid file attributes for 
this function. 

8 

8.3 


275 

File # xxx is already defined. 

8 

8.3 


276 

Invalid alternate key number - 
Must be in range 1 to 16. 

8 

8.3 


277 

Invalid alternate key for this 
file. 

8 

8.3 
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Error 

Niomber 

Error Message 

Severity 
Return Code 

Section 

Reference 

278 

File does not have alternate 
indices. 

8 

8.3 

279 

Alternate index number already 
used. 

8 

8.3 

280 

Expecting TO, SUB, or SUB' but 
XXX was found. 

8 

6.5 

281 

Pause interval must be in 
range 1 to 255. 

8 

00 

U) 

282 

Expecting TO or SUB after GO 
but XXX was found. 

8 

6.3, 6.4 

283 

A field attribute character 
(FAC) may not immediately 
precede a literal. 

8 

7.5 

284 

Expecting comma or BEG but xxx 
was found. 

8 

8.3 

285 

Label xxx already exists. 

8 

2.3 

286 

Label yyy was previously 
defined as a xxx. 

8 

2.3 

287 

Variable yyy was previously 
defined as a xxx. 

8 

3.3, 3.4 

288 

Function yyy was previously 
defined as a xxx. 

8 

4.4 

289 

Label xxx may not end with a 
$ or % character. 

8 

2.3 

290 

A string value may not be 
assigned to numeric receiver 
xxx. 

8 

3.2, 3.3 

291 

A numeric value may not be 
assigned to alpha receiver 
xxx. 

8 

3.2, 3.4 

292 

TRACE statement no longer 
supported - Use the symbolic 
debugger. 

8 

Appendix 
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Error 


Severity 

Section 


Number 

Error Message 

Return Code 

Reference 


293 

Null statement invalid after 

THEN or ELSE. 

8 

4.2, 5.2 


294 

yyy may not be declared as 

XXX variable. 

8 

3.2 


295 

Array dimension must be in 
the range 1 to 32767 - Default 
value of 10 used. 

6 

3.5 


296 

Format specifications must be 
greater than zero. 

8 

7.4 


297 

Expecting PIC but xxx was 
found. 

8 

7.5 


298 

The FILESEQ option is valid 
only for TAPE files. 

8 

8.3.2 


299 

OPTION BASE must precede DIM 
and COM statements and all 
array references. Statement 
ignored. 

4 

OPTION 
BASE 
entry; 
Part II 


300 

OPTION BASE previously 
specified. Statement ignored. 

4 

OPTION 
BASE 
entry; 
Part II 


301 

Array dimension must be in 
range of 0 to 32767. Default 
value of 10 used. 

6 

3.5.2 


302 

Expecting 0 or 1 but xxx was 
found. 

8 

OPTION 
BASE 
entry; 
Part II 


303 

Function xxx previously used 
with argument. 

8 

4.4.2 


304 

Function xxx previously used 
without argument. 

8 

4.4.2 


305 

Variable xxx previously defined 
as a scalar is being used as an 
array. 

8 

3.5.3 


306 

Variable xxx previously defined 
as an array is being used as a 
scalar. 

8 

3.3.3 
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Error 

Number 

Error Message 

Severity 
Return Code 

Section 

Reference 

307 

Function xxx may not invoke 
itself. 

8 

DEF entry; 
Part II 

308 

Expecting numeric expression 
but xxx was found. 

8 

3.3 

309 

Expecting alpha or numeric 
scalar variable but xxx 
was found. 

8 

3.3.3 

401 

Invalid operand in PRINT 
statement. 

8 

7.5 

402 

Compiler error. 

12 

1.4 

403 

Compiler error due to prior 
errors. 

12 

1.4 

404 

xxx invalid in USING list. 

8 

7.4 

405 

An invalid subroutine name or 
PRNAME has been corrected or 
replaced. 

4 

CO 

00 

in 

406 

Invalid OPEN option for this 
file access method. 

8 

8.3 

407 

Line number xxx missing before 
this line. 

6 

2.3 

408 

Constant invalid - Out of 
range. 

8 

3.3 

409 

SUB argument may not be 
declared in COMMON. 

6 

6.5 

410 

Invalid picture used in PACK, 
UNPACK, or CONVERT statement. 

6 

9.1 

411 

Invalid line length in SELECT 
statement. 

4 

8.3 

412 

FORM statement contains an 
invalid number in a FL or BI 
data specification. 

6 

2.3 

413 

Target line number is invalid 
for this type of statement. 

8 

6.4, 6.5 
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Error 

Number 

Error Messaqe 

Severity 
Return Code 

Section 

Reference 

414 

This file was not previously 
SELECTed. 

4 

8.3 

415 

File already specified in 

SELECT, POOL statement. 

4 

8.3 

416 

Code efficiency reduced due 
to complexity of expression. 

4 

4.3, 5.4 

417 

Invalid constant used as a 
subscript. 

8 

3.3, 3.4 

418 

Alternate key number must be 
in range 1 to 16. 

8 

8.3 

419 

Invalid alternate key 
specification. 

8 

8.3 

420 

File number must be within 
range 1 to 64. 

8 

8.3 

421 

This file has already been 
SELECTed. 

8 

8.3 

422 

Invalid record size specified. 

8 

8.3 

423 

The last character of the key 
is beyond the end of the 
record. 

8 

8.3 

424 

Target line number for EOD or 
DATA exit is invalid. 

8 

8.3 

425 

Integer matrix may not be the 
result operand of matrix 
inversion. 

8 

9.2 

426 

Prname truncated to eight 
characters. 

4 

8.3 

427 

Prname contains invalid 
character or starts with a 
digit. 

8 

8.3 

428 

Generated STATIC area too 
large. 

12 

1.4 
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Error 

Number 

Error Message 

Severity 
Return Code 

Section 

Reference 

429 

Program too large to compile: 

XXX. 

16 

1.4 

430 

The selected file is not an 
indexed file - Buffer pooling 
may not be used. 

4 

8.3 

431 

Compiler error: xxx. 

12 

1.4 

432 

User function or routine is 
not defined. 

6 

4.4, 6.4 

433 

Generated COMMON area too 
large. 

12 

6.5 

434 

Combined COMMON and STATIC 
areas too large. 

12 

6.5 

435 

Array xxx too large. 

12 

3.5 

436 

Block size invalid. 

4 

8.3 

437 

Invalid tape density. 

4 

8.3 

438 

Line numbers greater than 

65535 are incompatible with 
SYMBOLIC DEBUG - Use the 

EDITOR to renumber your 
program in smaller increments 
if you want to use the 
symbolic debugger. 

6 

1.4, 2.3 

439 

Statement will cause run-time 
Stack overflow. 

8 

1.4 

440 

Statement too long. 

12 

2.2, 2.3 

441 

Label xxx missing. 

6 

2.3, 6.2 

442 

Primary key length may not 
exceed 255 characters. 

8 

8.3 

443 

Alternate key extends beyond 
the end of the record. 

8 

8.3 
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Error 

Number 

Error Message 

Severity 
Return Code 

Section 

Reference 

444 

Alternate key length may not 
exceed 255 characters. 

8 

8.3 

445 

Alternate key number has 
already been specified for 
this file. 

8 

8.3 

446 

The sum of the lengths of 
the primary key and any 
alternate key may not exceed 

255 characters. 

8 

8.3 

447 

XXX, yyy is referred to only 
once in this program. Check 
for possible spelling errors. 

4 

M/A 

448 

Subscripts out of range in 

STR function. 

6 

5.5 

449 

KEY clause precedes KEYS 
clause in ACCEPT statement: 

KEYS clause will be ignored. 

4 

7.5 

450 

NEXT statement does not have a 
preceding matching FOR 
statement. 

8 

NEXT 

entry; 

Part II 

451 

FOR statement at line xxx does 
not have a following matching 
NEXT statement. 

8 

FOR entry; 
Part II 

452 

Index variable xxx on NEXT 
statement does not match 
preceding FOR index. 

8 

FOR entry; 
Part II 

453 

Illegal reference from statement 
xxx into FOR/NEXT loop at xxx. 

8 

FOR entry; 
Part II 

454 

FOR statement with index 
variable xxx is already active. 

8 

FOR entry; 
Part II 
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APPENDIX I 

CVBASIC USER AID (CONVERSION FROM VS BASIC 2.3 to 3.2 OR GREATER) 


I.l INTRODUCTION 

CVBASIC is an aid to help you convert from Version 2.3 of VS BASIC to 
Version 3.2 of VS BASIC. Since Version 3.2 programs are compatible 
with Version 3.4 programs, no further conversion is required. CVBASIC 
converts source code, residing in single files or libraries, from 
Version 2.3 syntax to 3.2 syntax. Input to the utility must be 
syntactically correct Version 2.3 source code. Once the conversion 
program is complete, the output source file/library is created and an 
update listing is produced that indicates the success or failure of 
the conversion. This listing can be displayed at the workstation, or 
it can be printed. If the conversion was not successful, an error 
message indicates the reason for the error and suggests corrective 
action. The output source code can then be compiled by a Version 3.2 
or above VS BASIC compiler. 

VS BASIC Versions 3.2 and above support variable names up to 64 
characters in length. CVBASIC accommodates this by inserting necessary 
spaces between the elements in the language, such as variables, 
reserved words, and constants. 

A summary of additional syntax changes that CVBASIC automatically 
converts includes the following items: 

1. Insert spaces around all VS BASIC reserved words. 

2. Convert the following: 

SELECT D to SELECT DEGREES, 

SELECT R to SELECT RADIANS, 

SELECT G to SELECT GRADS, 

SELECT P to SELECT PAUSE. 

3. Convert #PI to PI. 

4. Convert X to Y, (###) to CONVERT X to Y, PIC (###). 


CVBASIC User Aid (Conversion from VS BASIC 2.3 to 3.4 or Greater) I-l 



5. Convert FMT PD (X.Y) to FMT PD (X,Y). 

6. Convert TRANS (A$,B$)R to TRANS(A$,B$)REPLACING. 

7. Convert PACK (###) TO PACK PIC (###). 

8. Convert UNPACK (###) to UNPACK PIC (###). 

1.2 USING CVBASIC 


Figures I-l and 1-2 indicate the information needed to define the 
input and output of this program. Once CVBASIC is run successfully, 
the output source programs must then be compiled under Version 3.2 or 
above of the compiler. In addition, a listing of the files converted 
and any errors that occurred is produced. This error listing explains 
the conditions that prevented the conversion and provides possible 
error correction solutions. If the library option is chosen and any 
of the files in the library are not valid source files, those files 
are automatically skipped. The names of the skipped files are written 
to the error listing. 


r 




MESSAGE INPT BY CVBASiC 


This 


information REQUIRED by.program CVBASIC 
TO OEFINC INPUT 

CVBASIC - VS BASIC source conversion utility 
utility converts VS BASIC 2<3 source files to VS BASIC 3.2 source files. 
Please specify the file or^ilbrary to be converted: 


FILE 


= **»*»**'* library 


=? MLHLIB**. volume 


£ ZENITH 


and select: 

(2) Convert a single_f11e 

(3) Convert an entire 11brary_(leave the FILE name blank) 


or select: 

(13) Instructions 
(16) Exit from ‘ 


)m-CVB_ASIC j ‘ ^^ 




Figure I-l. Information Required for 
Define Input Screen for CVBASIC 
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—ppip-p———— 

MESSAGE FILE BY CVBASIC 

INFORMATION REQUIRED BY PROGRAM CVBASIC 
TO DEFINE OUNPUT 


CVBASIC - Source file conversion parameters 

Please ENTER the output file for the converted source 

or 

Press PF2 if you wish to replace input file MGLLOGON 
FILE s ***#***★ LIBRARY = MLHOBJ** VOLUME 


When the conversion has been completed, the results 
may be printed or displayed at the workstationa 

Or select: 

(13) Instructions 
(16) Return to main menu 


V __ 

Figure 1-2. Information Required for 
Define Output Screen for CVBASIC 



= ZENITH 






You can run CVBASIC from a procedure or from the Command Processor 
menu. The parameters needed for writing procedures are listed in the 
following table. Conversions can be run as batch tasks only if they 
are fully parameterized (see the VS Procedure Language Reference ). 


PRNAME 

Keyword 

Length 

(in 

bytes) 

Option 

Default 

INPUT 

FILE 

8 


Blank 

(main menu) 

LIBRARY 

VOLUME 

PF Keys* 

8 

6 

1 = Convert a file 

2 = Convert a 

library 

13 = Instructions 

16 = Exit program 

User's INLIB 
User’s INVOL 
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PRNAME 

Keyword 

Length 

(in 

bytes) 

Option 

Default 

OUTPUT 

FILE 

8 



(file) 

LIBRARY 

8 


User’s OUTLIB 


VOLUME 

PF Keys* 

6 

b = Continue 

2 = Replace input 

User's OUTVOL 




file 





13 = Instructions 

16 = Return to 





main menu 


OUTPUT 

LIBRARY 

8 


User’s OUTLIB 

(library) 

VOLUME 

6 


User’s OUTVOL 


NOTIFY 

3 

YES/NO 

NO 


PF Keys* 


13 = Instructions 

16 = Return to 





main menu 


PRINT 

FILE 

8 


CVBA + unique 

(output 




4-digit number 

listing) 

LIBRARY 

8 


User’s SPOOLIB 


VOLUME 

6 


User’s 

SPOOLVOL 

ERROR 

PF Keys* 


1 = Return to 


(if no 



main menu 


errors 



11 = Display results 


occurred) 



15 = Print results 

16 = Exit CVBASIC 


ERROR 

PF Keys* 


1 = Return to 


(if errors 



main menu 


occurred) 



11 = Display errors 

13 = Instructions 

15 = Print errors 

16 = Exit CVBASIC 


RENUMBER 

PF Keys* 


1 = Skip this file 


(edit the 



5 = Renumber this 


file and 



file 


renumber 

it) 



16 = Return to 

13 = Instructions 




main menu 


* The keyword is not required. 






1-4 CVBASIC User Aid (Conversion from VS BASIC 2.3 to 3.4 or Greater) 




If CVBASIC is run interactively from a workstation, the name of the 
file undergoing conversion processing is displayed along with file 
size information. If you select NOTIFY option or only one file is 
being converted, you are notified of any errors that occurred after 
the conversion is complete. If the error can be corrected by 
renumbering the file, you have the option of calling the Editor to 
renumber; the conversion is then automatically attempted again. If 
errors occur during processing, the error screen is displayed for you 
to display or print the listing, return to the CVBASIC main menu, or 
leave the program. 


1.3 PROGRAM EXAMPLE 


This is a compilable program under Release 2.3 of VS BASIC that must 
be converted before it can be run under Release 3.2 or above of VS 


BASIC: 


100 

SELECT D,P9 

200 

INPUTX 

300 

Y = SIN(X) 

400 

CONVERT Y TO Z$ 

500 

PRINTZ$ 

600 

GOTO200 


When this program is used as the input program file for CVBASIC, the 
resulting file is: 

100 SELECT DEGREES, PAUSE 9 
200 INPUT X 

300 Y = SIN(X) 

400 CONVERT Y TO Z$, PIC (##.##) 

500 PRINT Z$ 

600 GO TO 200 

Note that spaces were provided, that the abbreviated names were 
expanded to their more self-documenting form, and that the PIC clause 
was added. These changes make long variable names possible and 
generally increase the clarity, readability and self-documenting 
nature of VS BASIC. 
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GLOSSARY 




Term 


Definition 


alphanumeric 


alphanruneric 
array string 

alphanumeric 

expression 


alphanumeric 

variable 


A data type that represents uppercase and lowercase 
letters (A through Z, a through z), numbers (0 
through 9), and special characters (such as X, $, 

?). Each alphanumeric character requires one byte of 
storage. Languages such as FORTRAN and PL/I refer to 
alphanumeric data as character data. 

An alphanumeric array that is treated as a single 
data item. 

One or more literals, alphanumeric variables, 
alphanumeric array strings, or alphanumeric functions 
optionally joined as operands of alphanumeric 
operators. 

A variable that accepts alphanumeric data items. 


argument 

array 


array 

designator 


A data item used as input to a function or subroutine. 

A one- or two-dimensional set of data items with the 
same data type that can be referenced collectively by 
a common name (see array designator). 

An array name followed by a set of empty parentheses 
(e.g., AO). An array designator references the 
entire array as a unit. 


array element A single array data item. An individual array 

element can be referenced by a subscripted form of 
the name. 
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Term 


Definition 




associative 


bit 


buffer 


byte 

character 

string 

comment 


commutative 


concatenation 


consecutive 

file 

constant 


control- 
specification 

data- 

specification 
data type 


determinant- 

variable 


A mathematical property of an operation whereby the 
order in which a series of such operations is 
performed does not affect the result. For example, 
the expression A + B + C is associative because 
(A + B) + C = A + (B + C). 

(Binary digiT). The smallest unit of data storage. 

A bit can have the value zero or one. 

A temporary storage place for input or output data 
that compensates for the different rates of data flow 
v/hen transferring data from one device to another. 

Eight sequential bits that form a unit in memory. 

An alphanumeric data item enclosed in matching single 
or double quotes. 

Any user-written message. The VS BASIC compiler 
ignores comments, but puts them on listings as 
written. 

A mathematical property of an operation whereby the 
order in which its operands are placed does not 
affect the result. For example, the expression A+B 
is commutative because A + B = B + A. 

An alphanumeric operation that sequentially combines 
two or more alphanumeric strings into a single string. 

A file whose records can only be accessed 
sequentially or by relative record number. 

A value or literal data item that does not change in 
value. 

A clause in a format statement that specifies the 
relative location of an output data item. 

A clause in a format statement that determines the 
data type and format of input or output values. 

The property of a data item that determines the 
internal representation of the item and in what types 
of expressions the item can be used. VS BASIC 
supports alphanumeric, float binary, float decimal, 
and integer data types. 

A variable supplied by the programmer to receive the 
value of the matrix determinant that is calculated as 
part of an inversion operation. 
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Term 


dimension 


executable 

program 

executable 

statement 

expression 

Extend mode 

file- 

expression 

filename 

float binary 


float decimal 


format 

format 

specification 

function 


Definition 

The number of subscripts that an array can contain 
(i.e., whether the array is a vector or table). 

Also, the maximum number of elements in a given array 
dimension. A VS BASIC array can contain from 1 to 
32,767 elements in a particular dimension; the 
default number of elements is 10. 

A program that the processor can run. It consists of 
one compiled main program and, optionally, any number 
of compiled subprograms. 

A statement that calculates, tests, or changes the 
flow of control. 

One or more constants, variables, or functions, 
optionally connected by operators. 

An Open mode in v/hich a program can write to a 
consecutive file, but cannot read the file. 

A pound sign (#), followed by a numeric expression, 
that references a file in all file I/O operations. 

An alphanumeric value of up to eight characters that 
identifies a physical file. The value must begin 
with an alphabetic character, integer, @, $, or #, 
and cannot contain embedded spaces. 

A data type that represents fractional and very large 
and very small numbers in scientific notation. Float 
binary values can be values ranging from 
+5.4\x\10~^^ to +7.2 X 10^^. The range of float 
binary values is larger than that of the float 
decimal data type (see definition below), but float 
binary operations can lose precision in some cases. 

A data type that represents fractional and very large 
and very small numbers in scientific notation. Float 
decimal values represent a slightly smaller range of 
values (+1 X 10"®^ to + 1 x 10®^) than the float 
binary data type (see definition above), but float 
decimal operations are more precise. 

A statement that describes the arrangement of data. 

A clause in a format statement that creates a logical 
"picture" of the data being output. 

A subroutine that returns a single value. 
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Term 


Image 

indexed file 

Input mode 

integer 

intrinsic 

function 

I/O mode 

keyv/ord 

label 

library 

literal 

logical 

expression 

null label 

numeric 

constant 

numeric 

expression 

numeric scalar 
variable 


Definition 

A logical "picture" of the format desired for an 
output operation. 

A file whose records can be accessed either by key 
value or sequentially. 

An Open mode in which a program can read, but not 
modify, a file. 

A data type that represents whole numbers ranging 
from -2,147,483,648 to 2,147,483,647. 

A function that is defined by the compiler. 


An Open mode in which a program can both read and 
modify a file. 

A word defined for reserved use within a computer 
language. 

An identifier that is assigned to a statement for 
later reference. 

Identifies a physical file as existing in a 
particular group of files. The library name cannot 
exceed eight alphanumeric characters. The value must 
begin with either an alphabetic character, @, $, 
or #, and cannot contain embedded spaces. 

An alphanumeric data item whose value is fixed during 
program execution. 

An alphanumeric expression containing any of several 
logical operators (ADDC, ADD, AND, OR, XOR, BOOLh). 

A place-holder in GOTO or GOSUB statements that 
effects no transfer of control if the value of the 
tested expression equals the value of that place in 
the list of transfer points. 

A numeric data item whose value is fixed during 
program execution. 

One of a series of constants, variables, or functions 
connected by arithmetic operators. 

A variable that contains a single numeric value. 
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Term 


Definition 


numeric 

variable 

Output mode 


print file 


prname 


pseudovariable 

random 

access 


receiver 

relational 

expression 

scalar 

scalar 

variable 

sequential 

access 

Shared mode 


statement 

label 


string 

dimension 


subroutine 


A variable used to reference numeric data in memory. 


An Open mode in which a program can create and write 
records to a (possibly newly created) file. A 
program cannot read records from a file in Output 
mode. 

A consecutive file intended for use by the printer. 

A print file contains printer control bytes that 
control such printer operations as line feeds, page 
breaks, and the alarm. 

A literal string used as the parameter reference name 
for a given file. 

A function that acts as a receiver. 

A method of accessing records in a file in any order. 
An indexed file can be accessed randomly by a key 
value; a consecutive file can be accessed randomly by 
relative record number. 

A variable or function to which data can be assigned. 

An alphanumeric or numeric expression containing a 
relational (<, >, <=, >=, =, <>) operator. 

A value represented by a single data item. 

A variable containing a single value. 


A method of accessing a file's records in successive 
order. 

An Open mode in which a program can both read and 
modify records in an indexed or consecutive log file. 

A character string used as a label reference for a 
statement. A label must immediately precede the 
statement. 

The maximum length of an alphanumeric data item 
(character string). The length can range from 1 to 
256, inclusive, and defaults to 16. 

A subprogram that can be called to perform a service 
for the main program. 
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Term 


subscript 


substring 


variable 

volume 


word 


WP file 


Definition 

An integer expression that follows an array name to 
identify a particular array element. 

A portion of an alphanumeric variable that the STR 
function creates. STR forms the substring by 
abstracting a specified number of characters from a 
specified starting value in the original string 
variable. 

A named data item whose value can change. 

Identifies a physical file as residing on a specific 
disk or tape. The volume name can contain no more 
than six alphanumeric characters. The value must 
begin v/ith either an alphabetic character, integer, @, 
$, or #, and cannot contain embedded spaces. 

A group of bytes (four on the VS) that is treated, 
stored, and addressed as a unit. 

A consecutive disk file that is organized for access 
by VS Word Processing or the document access 
subroutines. WP files include VS word processing 
documents and OIS files. VS BASIC programs cannot 
access OIS files, and can only access VS word 
processing documents through the document access 
subroutines. 
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Document History 


Summary of Changes 

for the Fourth Edition of the VS BASIC Language Reference 


Description 

Change/New Feature 

Affected Pages 

Float Decimal 

Version 3.4.2 of VS BASIC supports 
float decimal numerics. The 
float decimal representation 
allows you to perform precise 
floating-point operations. 

I- 2, 1-9, 1-12, 

3- 2 to 3-5, 

4- 11, 4-12, 

II- 31 to 11-32, 
Appendix B, 
Appendix C 

CVDQ and CVQD 
subroutines 

These subroutines enable a 
program to interconvert float 
binary and float decimal 
variables. 

11-31 and 11-32 

Error Messages 

Three new error messages, 124, 

448, and 449, have been added. 

Appendix H 

EDITOR 

The description of the VS Editor 
has been updated to reflect the 
current release. 

1-6 to 1-11 

REWRITE and 

WRITE 

statements 

The restriction prohibiting 
concatenation in an expression 
in REWRITE and WRITE statements 
is described. 

11-150 and 

11-179 

Glossary 

A glossary that defines certain 

VS BASIC and data processing 
terms has been added. 

Glossary-1 to 
Glossary-6 

Index 

The Index has been updated. 

Index-i to 
Index-9 


miscellaneous editorial 
and technical corrections 




SUMMARY OF CHANGES 

FOR THE 3rd EDITION OF VS BASIC LANGUAGE REFERENCE 


TOPIC 

DESCRIPTION 

PAGES 

PRINT FILES 

CLOSE PRINTER 

140 


SELECT PRINTER 

140, 256 

Miscellaneous 

Technical and 

220, 253 


Editorial 

256, 266 
277 
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SUMMARY OF CHANGES 

FOR THE 2nd EDITION OF VS BASIC LANGUAGE REFERENCE 


TOPIC 

DESCRIPTION 

PAGES 

Release 

3.2 

Prerelease 3.2 

Release 3.2 


Syntax Changes 


Required spacing within 





a statement 

14,15 



One or two character 

Long variable names 

18 



variable names 





#PI intrinsic function 

PI intrinsic function 

35,214,235 



SELECT D 

SELECT DEGREES 

36,256 



SELECT G 

SELECT GRADS 

36,256 



SELECT R 

SELECT RADIANS 

36,256 




Statement labels 

62,63 




FILESEQ for tape files 

100,220-223 




CLOSE WS 

140 




CLOSE CRT 

140 



CONVERT X TO ¥$,(###) 

CONVERT X TO y$,PIC(###) 

142 



FMT PD (6.4) 

FMT PD (6.4) 

152-154 



Nonnumeric file, li- 

Numeric file, library. 




brary, and volume name 

and volume name 




only 


220 



PACK (###) 

PACK PIC (###) 

225,226 




SELECT WS 

256 



SELECT P 

SELECT PAUSE 

256 



TRAN [R] 

TRAN [REPLACING] 

273 



UNPACK (###) 

UNPACK PIC (###) 

274 

General 

Miscellaneous editorial changes 






DH-3 





Index 





INDEX 


ABS (absolute value) function. 


4-7, 4-13, 4-15, 4- 

-16, II-2, 

11-104 


ACCEPT statement, 1-2, 

4-13, 5-17, 

6-2, 7-2, 7-6, 7-9 

to 7-18, 

II-3 to II-8 


^ ALT clause, 7-15 


AT clause, 7-1, 7-9, 

7-11, 

7-17, 11-139 


CH clause, 7-7, 7-9, 

7-12, II-4, 


11-51 


COL clause, 7-7, 

7-17, 

11-50, 

11-139 



data entry, 7-12 
data validation. 

7-12 


FAC clause, 7-9, 

7-11 

to 7-12, 

II-4 



execution, II-8 
fields, 7-10 to 

7-11, 

II-4 to 


II-6 

KEY clause, 7-15 
KEYS clause, 7-14 
NOALT clause, 7-10, 7-15 to 7-16 
ON KEY clause, 7-15 
PP keys, 7-14, II-7, 11-148 
PIC clause, 7-7, 7-9, 7-12, II-4, 
11-122 

positioning data, 7-10 
RANGE clause, 7-9, 7-13 
screen formatting, 7-10 
USING clause, 7-1, 7-6 
validation, II-6 
XX clause, 7-7, 11-50 
ADD[C], 5-11, 5-12, 5-13, 5-16, 

9-1, II-9 to II-IO 


Addition, 4-1 to 4-3 
priority of, 4-3 

ADDR-type subroutines, 6-9, 6-12 
to 6-13, 11-22, 11-31, 11-169 
to 11-170 

ALL, 5-6, 5-11, 5-16, II-ll 
Alpha array element, 3-6, 5-15, 
Glossary-1 

Alpha array name, 5-15 
Alpha array strings, 5-4, 5-15, 
6-17, 11-168, Glossary-1 
Alpha expressions, 5-5, 11-78 to 
11-79, 11-137 

Alpha receivers, 3-2, 5-5, 11-71, 
11-80 to 11-81, 11-155, 11-168 
Alpha variable, 3-10 to 3-11, 5-1, 
5-2 to 5-3, 5-14, 11-45 
Alpha variable name, 3-13 to 3-14 
Alphanumeric, 3-1, 3-7 to 3-10, 5-1 
array, 3-10 

assignment operator, 5-1 
character strings, 3-8 
constants (see literal 

strings), 3-1, 3-8 to 3-10 
data, 3-1, 3-2, 3-7, 5-3, 5-14 
definition of, Glossary-1 
expressions, 3-1, 5-1, 5-3, 5-5, 
5-14, 5-16, 5-17, Glossary-3 
functions, 5-1, 5-6, 9-1 
label, statement, 1-1, 11-113 
length, 5-14, 11-25, 11-78 to 
11-79 

literal strings, 3-8 to 3-10, 

5-15 
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INDEX (continued) 


operations, 1-2, 5-16 to 5-17 
operators (see also 

alphanumeric data, logical 
operators with), 5-1 to 5-4 
11-12, 11-121 

receivers, 3-2, 5-1, 5-5, 5-16, 
11-71, 11-80, 11-124 to 11-132 
scalar, 3-10, 5-15, 11-45, 11-78 
to 11-79 

statement label, 1-1, II-lll 
summary of terms, 5-15 to 5-16 
variables, 5-1 to 5-3, 5-14, 

3- 1, 3-10 to 3-11, 11-25, 
Glossary-1 

Alphanumeric data formats, 3-1, 

5-14 to 5-16 

alphanumeric length, 5-14, 11-71, 
11-78 

defined length, 5-14, 11-71 
AND logical operator, 5-11 to 

5- 13, 9-1, 11-12 

ARCCOS (arccosine) function, 4-6, 

4- 16, 11-13, 11-103 
ARCSIN (arcsine) function, 4-6, 

4-16, 11-14, 11-103 
ARCTAN (arctangent) function, 

4-6, 4-16, 11-15, 11-103 
Argument, 4-1, 4-5 to 4-10, 

6- 10, 11-121, Glossary-1 
dummy, 4-12 
expressions, 4-5 

in user-defined 
functions, 4-6, 4-12 
list, 6-5 
TO, 11-155 
types, 6-16 to 6-17 
Arithmetic 

mixed-mode, 4-13 
Arithmetic operator, 4-1 to 4-5, 
9-1 

Array, 3-1, 3-10 to 3-17, 11-85 to 
11-102, 11-155 
alphanumeric, 3-9 
array strings, 5-4, 5-14 
comparison between one- and 
two-dimensional, 3-14 to 3-17 
constant, 3-1 

default dimensions, 3-14, 3-17 
defining, 3-11 


definition of, Glossary-1 
dimensioning, 3-14 to 3-17, 9-3, 
to 9-4, 11-43 to 11-44, 11-85 
to 11-102 

elements of, 3-1, 3-6, 3-11, 
3-15, Glossary-1 
expressions in, 3-1, 3-2, 3-4, 

3- 12 to 3-13, 3-15 

input values for, through INPUT 
statement, 11-72 to 11-75 
length of elements, 3-16 to 3-17 
naming, 3-12 
numeric, 4-8, 4-16 
one-dimensional, 3-14 to 3-15 
passing, 6-17 

subscripts, 3-12 to 3-16, 11-120 
two-dimensional, 3-14 to 3-16 
variable, 3-1, 3-10 to 3-13, 

5-4, 11-43, 11-45 
Array assignment statement, 9-2 
operations with, 9-2 
redimensioning arrays with, 

9-2 to 9-3 

Array designator, 4-7, 4-9, 

4- 16, 5-4, 6-17 

definition of, 3-13, Glossary-1 
Array variables, 3-1, 3-10 to 3-13 
Assignment operator, 4-1 to 4-2 
Assignment statement, 4-2, 6-6, 

9-2 

Associative, definition of, 
Glossary-2 

ATN (arctangent) function, 4-6, 
4-16, 11-16, 11-103 

B 


BACKTAB key, 7-13 
BASIC and COBOL, D-1 to D-3 
BASIC character set, E-1 
BASIC compiler, 1-6, 1-9 to 1-12, 
B-1 to B-3 
DPLOAT, 1-10, B-3 
ERRLIST, B-3 
FILECLAS, 1-11 
FLAG, B-3 

input definition, 1-10 
LINES, B-3 
LOAD, 1-9, B-2 
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BASIC Compiler (continued) 

MINANS, 1-10, B-3 
(see also MINANS) 
options, 1-9, B-1 to B-3 
output definition, 1-10 
PMAP, B-1 
RECORDS, 1-10 
RELEASE, 1-11 
RETAIN, 1-11 
SOURCE, 1-10, B-1 
STOP, 11-167, B-3 
SUBCHK, B-3 
SYMB, 1-10, B-2 
XREF, B-2 

BASIC reserved words, A-1 to A-2 
BASIC statements, II-l to 11-181 
BASIC syntax, II-l 
BIN function, 4-13, 5-6, 5-14, 

7-15, 9-1, 11-17 
Binary operation, 4-7, 4-14 to 

4- 15, 9-1 

Bit, definition of, Glossary-2 
Blanks, 2-3 to 2-4, 3-9, 3-11, 5-2 
to 5-3, 6-15, 11-73 
in Image {%) statement, 11-69 to 
11-70, 

in INPUT statement, 11-72 
Blocks clause, 8-11, 8-12 
Boolean logic functions, 1-2, 9-1 
BOOLh logical operator, 5-11, 

5- 12, 5-13, 9-1, 11-18 to 11-19 
Branching, 2-4, 2-5, 6-2 

conditional, 6-2 
error, 8-19 
instructions, 2-5 
program, 2-5, 6-2 
subroutine, 6-2, 6-5, 11-74 
unconditional, 6-2 
with keys, 7-15 

Buffer, definition of, Glossary-2 
Byte, definition of, Glossary-2 


CALL statement, 2-5, 4-13, 6-1, 

6-2, 6-4, 6-8 to 6-17, 11-20 to 
11-22, 11-31 to 11-32, 11-169 


Character set, VS, E-1 

ASCII collating sequence, G-1 
field attribute, F-1 
Character string, 3-8, 3-10 to 3-12 
Glossary-2 
CIRCUMF, 3-1 to 3-2 
Clauses, see ACCEPT 
blocks, 8-11, 8-12 
USING, 8-13 to 8-16 
CLOSE statement, 8-8, 11-23 to 
11-24 

Closing files (see CLOSE 

statement), 8-8, 11-23 to 11-24 
colon, 2-4, 2-6, 2-7, 11-52, 11-145 
COM statement, 3-10, 3-11, 3-16 to 
3-17, 6-10, 6-13 to 6-14, 6-16, 
11-25 to 11-26, 11-43, 11-88, 
11-91, 11-97, 11-102, 11-170 
Comma, 11-48 

as an insertion character in 
FMT statement, 11-50 
use in INPUT statements, 11-72 
use in LET statements, 11-80 
use in MAT INPUT statements, 

II-Ol 

use in ON statements, 11-113 
use in PRINT statements, 11-69 to 
11-70, 11-135 

Comment, 2-5 to 2-6, Glossary-2 
in program, 2-5, 2-6 
in REM statement, 2-6 
in * statement, 2-6 
Common variable, 6-10 
Commutative, definition of, 
Glossary-2 

Compiler, 1-4, B-1 to B-3 

BASIC, 1-4, 1-6, 1-9 to 1-11, 

B-1 to B-3 
EDITOR, 1-6 to 1-9 
Compiler directives, 2-7 
Compiler options, 1-3, 1-9 to 1-10, 
B-1 to B-3 
Compiling, 6-10 

Computed GOSUB statement, 11-57 
Concatenation (&), 5-1, 5-2 to 5-3, 
5-5, 5-11, Glossary-2 
Consecutive files, 8-2, 8-3, 

11-165, 11-179, Glossary-2 
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Constants, 3-1 to 3-2, 3-5, 3-8 to 

3- 10, 4-5, 4-15 

definition of, 3-1, Glossary-2 
float binary, 3-4 
float decimal, 3-4, C-3, C-4 
floating-point, 3-4, 3-5 
integer, 3-6, C-3, C-4, C-6 
intrinsic named, 4-6 
PI intrinsic, 11-133 
Control specification, in FMT 
statement (see also POS, 

SKIP, and X), 11-50, 11-52, 
11-136, 11-165, Glossary-2 
Control statements, 6-1 to 6-19 
branching, 6-2 
conditional, 6-2 
exit conditions, 6-2 
halting execution, 6-1 
looping, 6-2, 11-53, II-lll 
subroutine, 6-2, 11-169 
unconditional, 6-2 
Control variable, in FOR 
statement, 11-53 
CONVERT statement, 4-13, 6-2, 

9-1, 11-27 to 11-28 
COPY statement, 11-29 
COS (cosine) function, 4-7, 

4- 16, 11-30, 11-103 
Current column, 11-45 
Current length, 3-12 
Current row, 11-45 
Current value, 3-12 
Cursor, 1-3 

Cursor control keys, 1-3, 7-13 
CVBASIC, I-l to 1-5 
CVDQ subroutine, 3-3, 11-31 
CVQD subroutine, 3-3, 11-32 


Data (see alphanumeric and 
numeric), 3-1 

alphanumeric, 3-1, 3-8 to 3-10 
conversion, 9-1, 11-56, 11-103 
exit, 11-56 

extraction (GET), 11-56, 
floating-point, 3-2 to 3-7, 4-13 
formats, 3-1 to 3-17 


in FMT statement, 11-50 to 
11-52, 11-56 

in Image {%) statement, 11-56, 
11-69 to 11-70 

in INPUT statement, 11-72 to 
11-75 

in scalar assignment statement, 
(LET), 11-80 to 11-81 
integer, 4-14 to 4-16 
list pointer, 11-142 
literals (alphanumeric 
constants), 3-8 to 3-10 
numeric, 3-2 to 3-7, 4-1, 4-13 
storage, 11-124 to 11-132 
DATA 

clause, 6-2 
error, 8-19 to 8-20 
Data Management System (DMS), 1-4, 
8-2, 8-3, 8-5, 8-7, 8-11, 8-12 
buffer, 8-11, 8-12 
error recovery, 8-19 
Data specification, definition 
of, Glossary-2 

DATA statement, 11-33, 11-97 
relationship to READ statement, 
11-33, 11-56, 11-142 
relationship to RESTORE 
statement, 11-33, 11-142 
Data type, definition of, 

Glossary-2 

DATE function, 5-6, 5-14, 11-34 
Decimal point (.) 
format, C-3, C-4 

in PRINT statement, 11-69, 11-135 
insertion character in FMT 
statement, 11-50 
DEP statement, 4-12, 11-35 to 
11-36 

DEF FN’ statement, 6-4 to 6-8, 
11-38, 11-74 

DEF function definition, 4-12, 

4-15, 11-35 to 11-36 
Defining 

COM statement, 3-16 to 3-17, 

6-10, 6-13, 11-25 to 11-26 
DIM statement, 3-16 to 3-17, 

6-18, 11-43 to 11-44 
functions, 4-6, 4-12, 4-15 


Index-4 



INDEX (continued) 




DELETE statement, 8-10, 8-11, 

11-42 

restriction with consecutive 
files, 11-42 

Delimiters (see PRINT, INPUT), 
11-115 

Descriptor, 6-12 

Determinant-variable, definition 
of, Glossary-2 

DFLOAT, 1-10, B-3 

DIAM, 3-2 

Dimension, definition of, 
Glossary-2 

DIM function, 4-7, 4-9, 4-13, 

4-15, 11-45 

DIM statement, 3-10, 3-16 to 3-17, 

6-18, 11-43 to 11-44, 11-88, 
11-91, 11-97, 11-102, 11-170 
defining alphanumeric data 
with, 11-43 

defining arrays with, 3-14 to 
3-15, 11-43 

Display, 
mode, 7-2 
workstation, 7-3 

DISPLAY statement, 1-1, 7-1, 7-17 
to 7-18, 11-46 

Document Access Subroutines, 8-2, 
8-4 

DPACK keyword in OPEN statement, 
11-116 

DUM, 6-7 

Dummy variable, 4-12, 6-6, 11-35 


E 




EDITOR, 1-6 to 1-9, 2-3 
EJECT compiler directive, 2-7, 
11-47 

ELSE keyword in IF statement, 
6-1, 6-2, 11-67 to 11-68 
END statement, 4-13, 6-1, 11-48 
EOD 

clause, 6-2 
definition of, 11-161 
errors, 8-19 
exit, 11-165 
ERRLIST, B-3 


Error 

branch, 8-19, 8-20 
messages, H-1 to H-13 
recovery, 8-19 to 8-20 
exclamation point, 2-5, 2-7 
Executable program, definition of, 
Glossary-3 

Executable statement, definition 
of, Glossary-3 
Exiting, 6-2 

EXP (natural exponential) 

function, 4-7, 4-8, 4-16, 
11-49, 11-104 
Expression, 

definition of,3-2, 4-1, 

6-16, Glossary-3 
evaluation of, 4-2 to 4-4 
logical, 5-13, 11-121 
mixed-mode, 3-4 
numeric, 4-5, 4-15, 11-136 
operation, 4-5 

relational operators in, 4-1, 

4-4 

value, 4-1 

Extend mode, definition of, 8-9, 
8-11, Glossary-3 

External subroutines, 6-4, 6-8 to 
6-19, 11-169 

argument types, 6-16 to 6-18 
arguments, 6-10 to 6-13 
common variables, 6-13 to 6-14 
compiling, 6-10 
form, 6-9 

initialization, 6-15 

linking, 6-10 

operation of, 6-8 to 6-9 

passing values, 6-10 to 6-14 

running, 6-10 

use of, 6-18 to 6-19 


F 


FAC (Field Attribute Character), 

7- 4 to 7-6, F-1 

Field format, 11-126 to 11-127 
Field types, 11-116, 11-127 to 
11-130 

File expression, definition of, 

8- 17 to 8-18, Glossary-3 
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File, 

definition of, 1-5, 8-1 
hierarchy, 1-5 

filename, 1-5, 11-115, Glossary-3 
library, 1-5, 11-115, Glossary-4 
records, 8-1 

volume, 1-5, 11-115, Glossary-5 
File I/O buffering and record 
area, 8-11 to 8-12 
File I/O modes, 8-10 to 8-11 
File input/output statements, 

8-1, 8-13 to 8-16 
buffering, 8-11 to 8-12 
data representation, 8-12, 8-16 
errors, 8-19 
examples, 8-17 to 8-18 
CLOSE statement, 8-8 to 8-9, 

11-23 to 11-24 

DELETE statement, 8-13, 11-42 
GET statement, 8-12, 8-13 to 
8-15, 8-20, 11-56, 11-69, 
11-144, 11-165 

intrinsic functions, 8-16 to 
8-18 

modes, 8-10 to 8-11 
OPEN statement, 8-7, 8-8 to 
8-9, 8-14, 11-115 to 11-118, 
11-144 

PUT statement, 8-13 to 8-15, 

8-20, 11-56, 11-69, 11-140, 
11-150 

READ statement, 8-12, 8-13 to 
8-15, 8-20, 11-56, 11-142 to 
11-143, 11-161 
record area, 8-11 to 8-12 
REWRITE statement, 8-13 to 8-16, 
8-20, 11-56, 11-77, 11-84, 
11-150 to 11-151 

status (FS fruiction), 5-6, 5-14, 
8-16 to 8-18, 11-55 
WRITE statement, 8-12, 8-13 
to 8-16, 8-20, 11-56, 11-77, 
11-84, 11-165 to 11-166, 

11-179 to 11-180 
File status, 5-14, 8-17, 11-55 
File types, 8-2 to 8-4 
File name, definition of, 1-5, 
Glossary-3 
Files, 1-5, 8-1 


FILESEQ keyword in OPEN 
statement, 11-116 
Float binary, 1-2, 3-2 to 3-5, 

4-7, 4-14, 4-15, 11-31, 11-32, 
C-1 to C-4, Glossary-3 
Float decimal, 1-2, 3-2 to 3-5, 
4-7, 4-13, 4-14, 11-31, 11-32, 
C-1 to C-4, Glossary-3 
Floating-point and integer 
calculation, 1-2, 3-3, 3-4, 

C-1 to C-4 

Floating-point calculation, 1-2, 
3-2 to 3-4, 11-31, 11-32, 

C-1 to C-4 

Floating-point constant, 

(E-format), definition of, 

3- 4 to 3-5, 4-13, 4-15 
Floating-point data, 3-2 to 3-7, 

4- 13 

Floating-point format, 1-2 
FMT statement, 7-6, 7-7, 7-8, 

8-13 to 8-16, 11-47 to 11-49 
use of, 7-6, 11-50 to 11-52, 
11-150 

used with files, 11-46 
used with PRINT USING, 11-50, 
11-136 

FOR statement, 2-5, 6-2, 11-53, 
II-lll 

FORM statement, 11-54 
Format, definition of, Glossary-3 
line, 2-2 to 2-4 
spacing, 2-3 

Format control specifications in 
FMT Statement (see also X, 

POS, SKIP), 7-5, 7-6, 11-50 
to 11-52, 11-54, 11-135, 
11-165, Glossary-3 
FS function, 5-6, 5-14, 8-16 to 
8-18, 11-55 
Functions 

ABS, 4-7, 4-13, 4-15, 4-16, 

II-2, 11-104 

ALL, 5-6, 5-11, 5-16, II-ll 
ARCCOS, 4-6, 4-16, 11-13, 11-103 

ARCSIN, 4-6, 4-16, 11-14, 11-103 

ARCTAN, 4-6, 4-16, 11-15, 11-103 

ATN, 4-6, 4-16, 11-16, 11-103 
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BIN, 4-13, 5-6, 5-14, 7-15, 9-1, 
11-17 

Boolean, 1-2, 9-1, 11-18 to 11-19 
COS, 4-6, 4-7, 4-16, 11-30, 

11-103 

DATE, 5-6, 5-14, 5-16, 11-34 
DEF, 4-12, 4-15, 11-35, 11-36 
defining, 4-6, 4-12 to 4-13 
definition of, 4-1, Glossary-3 
DIM, 4-7, 4-9, 4-13, 4-15, 11-45 
EXP, 4-7, 4-16, 11-49, 11-104 
expression, 4-5 
FS, 5-6, 5-14, 8-16 to 8-18, 

11-55 


HEX, 

7-14 
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11-61 
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-104 
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5 

-14, 

8- 

17 

to 8 

-18, 
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-77, 

II 

-144 





LEN, 

4-8, 

4 

-13, 

4- 

15, 

5-7 

U1 

1 

II 

-45, 

II 

-72, 

II 

-78 

to 

11-79 

LGT, 

4-8, 

4 

-16, 

II 

-82 

, II 

-104 

LOG, 

4-8, 

4 

-16, 

II 

-83 

, II 

-104 


logical, 5-1, 5-11 

MASK, 5-6, 5-14, 8-18, 11-84 

mathematical, 11-103 

MAX (maximum value), 4-8, 

4-13, 4-14, 4-15, 4-16, 11-105, 
11-108 


SGN, 4-9, 4-11, 4-13, 4-15, 4-16, 
11-104, 11-162 

SIN, 4-1, 4-6, 4-16, 11-103, 
11-163 

SIZE, 4-6, 4-9, 4-13, 4-15, 8-18, 
11-164 

SQR, 4-1, 4-9, 4-16, 11-104, 
11-166 

STR, 5-5 to 5-6, 5-14, 11-78 to 
11-79, 11-168 

TAN, 4-6, 4-16, 11-103, 11-172 
TIME, 5-14, 5-16, 11-173 
trigonometric, 4-6, 11-103 
user-defined, 4-12, 4-15 
VAL, 4-9, 4-13, 4-15, 5-7, 5-10, 
9-1, 11-178 


GETPARM, 8-7, 8-8, 8-9, 8-10 
GET statement, 4-13, 8-12, 8-13 to 
8-15, 8-20, 11-56, 11-69, 
11-144, 11-165 

GOSUB statement, 2-5, 6-1, 6-2, 

6-4 to 6-8, 8-19, 11-57, 
11-113, 11-148 

GOSUB' statement, 2-5, 4-13, 6-1, 
6-2, 6-4 to 6-8, 11-39, 11-40, 
11-58, 11-74, 11-148 
GOTO statement, 2-1, 2-5, 4-13, 
6-1, 6-2, 8-19, 11-60 


MIN (minimum value), 4-8, 

4- 13, 4-14, 4-15, 4-16, 11-105, 
11-109 

MOD, 4-8, 4-13, 4-14, 4-16, 
11-106, II-llO 

NUM, 4-8, 4-13, 4-15, 5-7, 11-112 
numeric, 4-5 

other numeric, 4-7 to 4-9, 11-97 
PI, 4-6, 4-16, 11-107, 11-122, 
11-133 

POS, 4-4, 4-8, 4-13, 4-15, 5-3, 

5- 7, 5-9 to 5-11, 11-79, 11-134 
requests, 11-117 to 11-118 
RECORD, 11-144 

RND, 4-8, 4-9 to 4-11, 4-16, 
11-152 

ROUND, 4-8, 4-9 to 4-11, 4-16, 
11-152, 11-154, C-3 


11-113 

H 


Hexadecimal/decimal conversion, 

I- 2, 3-3, C-1 to C-4 
Hexadecimal function (HEX), 7-14, 

II- 61 

HEX function, 11-61 
HEXOF alpha-expression, 11-137 
HEXPACK statement, 9-1, 11-62 to 
11-64 

HEXPRINT statement, 11-65 
HEXUNPACK statement, 9-1, 11-66 
HOLD option, 11-150 
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IF statement, 2-1, 2-5, 4-4, 6-1, 

6- 2, 11-67 to 11-68 

Image, definition of, Glossary-4 
Image {%) statement, 2-2, 2-4, 7-6 
to 7-7, 7-8 to 7-9, 8-12 to 
8-16, 11-50, 11-69 to 11-70 
use of, 7-7 to 7-8, 11-69 to 
11-70, 11-136, 11-150 
Indexed files, 8-2 to 8-3, 8-17, 
11-150, 11-179, Glossary-4 
alternate keys, 8-2, 11-77, 11-84 
data blocks, 8-3 
index blocks, 8-3 
mask, 8-2, 11-84 
primary key, 8-2, 11-77 
INIT statement, 11-71 
Initialization, 6-15 
Input mode, 8-1, 11-74, Glossary-4 
INPUT statement, 4-13, 6-1, 6-5, 

7- 2, 7-5, 7-9, 11-19, 11-38, 
11-72 to 11-75 

Input/output statements, 7-1, 

7-2, 8-1 to 8-12, 9-2, 11-69 to 
11-70 

ACCEPT, 4-13, 7-2, 7-9, 7-15 to 
7-16, 9-2, II-3 to II-8 
CLOSE, 8-5 to 8-8, 11-23 
DELETE, 8-10, 8-11, 8-12, 11-42 
DISPLAY, 7-1, 7-2, 7-16, 7-17, 
11-46 

GET, 4-3, 5-17, 8-14, 8-15, 8-20, 
11-56, 11-69, 11-144, 11-165 
INPUT, 4-13, 6-2, 6-4, 7-2, 7-5, 
7-9, 11-38, 11-39, 11-72 to 
11-75 

MAT INPUT, 9-2, 9-3, 11-85 to 
11-87, 11-90 to 11-92 
MAT PRINT, 9-2, 11-89. 11-90, 
11-94, 11-95, 11-96 
MAT READ, 9-2, 9-3, 11-97 
OPEN, 8-7 to 8-9, 8-12, 8-14, 
11-115 to 11-116, 11-144 
PRINT, 4-5, 7-1 to 7-3, 7-6, 

7-17, 11-50, 11-65, 11-69 to 
11-70, 11-135 to 11-139 
PUT, 8-12, 8-15, 8-20, 11-56, 
11-69, 11-140, 11-150 


READ, 4-13, 8-10, 8-12, 8-13, 

8-15, 8-19, 8-20, 11-56, 

11-142 to 11-143, 11-165 
REWRITE, 8-10, 8-15, 8-20, 

11-56, 11-77, 11-84, 11-150 to 
11-151 

WRITE, 8-10, 8-14, 8-19, 8-20, 
11-56, 11-77, 11-84, 11-179 to 
11-180 

INT (integer) function, 4-8, 4-16, 
11-76, 11-104 

Integer, definition of, Glossary-4 
Integer calculation, 3-4, C-1 
Integer constants, 3-6, 4-14 
Integer data, 3-2, 4-14 to 4-15 
Integer format, 1-2, C-1 
Internal subroutines, 6-4 to 6-8 
Intrinsic functions, 4-6 to 4-11, 
8-16 to 8-18, Glossary-4 
FS, 5-6, 5-14, 8-15, 11-55 
KEY, 5-6, 5-14, 8-15 to 8-16, 
11-77 

MASK, 5-6, 5-14, 8-16, 11-84 
PI, 11-133 

SIZE, 4-9, 4-13, 4-15, 8-16, 
11-164 
lOERR 

clause, 6-2, 8-20 
errors, 8-19 

I/O mode, 8-8, Glossary-4 
IPACK keyword in OPEN statement, 
11-116 

K 


KEY function, 5-6, 5-14, 8-17 to 
8-18, 11-77, 11-144 
Keyword, definition of, 
Glossary-4 

L 


Label, 

definition of, Glossary-4 
statement, 6-2 to 6-4, 11-113 
LEN (length of character string) 
function, 4-8, 4-13, 4-15, 
5-14, 5-7, 11-78 to 11-79 
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LET statement, 2-1, 4-2, 4-5, 4-13, 
5-17, 11-80 to 11-81 
LGT (logarithm to base 10) 
function, 4-8, 4-16, 11-82, 

11-104 

Library, 1-4, 1-5, Glossary-4 
Line format, 2-2 to 2-5 
multiple statement, 2-4 
sequence of execution, 2-5 
Line number, 11-113 
LINKER utility, 1-12, 6-10, 11-31, 
11-32 

Linking, 6-10 

Literal, definition of, 3-1, 3-8, 
Glossary-4 

literal string, 2-5, 3-8 to 3-10, 
5-3 

LOAD, B-2 

LOG (logarithm to base e) 

function, 4-8, 4-16, 11-82, 
11-104 

Logging on, 1-3 
Logical expressions, 5-11 to 
5-12, Glossary-4 
Logical operators, 5-12 to 5-13, 
11-12, 11-121 

Looping, 6-2, 11-53, II-lll 
M 


Machine language, 1-5 
MASK function, 5-6, 5-14, 8-16, 
11-84 

MAT ASORT/DSORT, 9-3, 11-86 to 
11-87 

MAT CON, 9-2, 9-3, 11-88 
MAT IDN, 9-2, 9-3, 11-90 
MAT INPUT, 9-2, 9-3, 11-91 to 11-92 
MAT INV, 9-3, 11-93 to 11-94 
MAT PRINT, 9-2, 11-96 
MAT READ, 9-2, 9-3, 11-97 
MAT REDIM, 6-18, 9-3, 9-4, 11-43, 
11-98, 11-170 
MAT TRN, 9-2, II-lOl 
MAT ZER, 9-2, 9-3, 11-102 
MAT =, 9-2, 11-89 
MAT +, 9-3, 11-78 
MAT -, 9-3, Il-lOO 
MAT *, 9-3, 11-99 


MAT ()*, 9-3, 11-99 
Mathematical functions, 11-103 to 
11-107 

Matrix, operations with 
addition, 9-2, 11-85 
array dimensioning, 9-3, 11-85 
arithmetic statements, 9-3 
assignment statements, 9-2 
identity function, 9-2, 11-90 
inverse function, 9-3, 11-93 to 
11-94 

I/O statements, 9-2 
matrix multiplication, 9-2, 

9-4, 11-95 

redimensioning, 11-85, 11-88 
sort, 9-3, 9-4. 11-86 to 11-87 
statement rules, 9-4 to 9-5 
statements, 9-2 to 9-5 
subroutines, 11-169 to 11-171 
subtraction, 9-2, 9-3, Il-lOO 
transpose function, 9-2, 9-4, 
II-lOl 

MAX (maximum value) function, 

4-8, 4-13, 4-14, 4-15, 

4-16, 11-105, 11-108 
Menus, 1-3 

Command Processor, 1-3 
MIN (minimum value) function, 

4-8, 4-13, 4-14, 4-15, 

4-16, 11-105, 11-109 
MINANS, 1-2, 1-10, 2-3, 2-4, 2-6, 

4- 3, 4-10, 4-12, 4-14, 5-3, 

5- 15, 6-1, 6-2, 6-7, 6-13, 

6- 14, 7-2, 7-17, 9-3, 11-25, 
11-33, 11-35, 11-43, 11-46, 
11-53, 11-72 to 11-73, 11-78, 
11-81, 11-91, 11-92, 11-97, 
11-98, II-lll, 11-114, 11-136, 
11-137, 11-141, 11-145, 

11-152, 11-167, B-3, C-4 

Mixed-mode arithmetic, 4-13 
Mixed-mode, definition of, 3-4 
MOD function, 4-8, 4-13, 4-14, 
4-15, 4-16, 11-106, II-llO 
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0 


NEW LINE key, 7-13 
NEXT statement, 2-5, 6-1, 6-2, 
11-53, II-lll 
NODISPLAY keyword in OPEN 

statement, 8-8 to 8-9, 11-115, 
11-116 

NOGETPARM keyword in OPEN 

statement, 8-8 to 8-9, 11-115, 
11-116 

null label, definition of, 
Glossary-4 
null line, 2-4 

NUM (number of numeric characters 
in a character string) 
function, 4-8, 4-13, 4-15, 

5-7, 5-8, 11-112 
Number, definition of, 3-1 
Numeric 

array-designator, 4-16, 11-155 
array name, 4-16 
array variable, 4-16 
constants, definition of, 
Glossary-4 

data, 3-2 to 3-7, 4-1, 4-13 
expressions, 4-3 to 4-5, 

11-136, Glossary-4 
functions (see Functions), 4-5 
functions with alpha 


arguments 

, 4-12 

, 5-7 

to 5-11 

LEN, 4-8, 

4-13, 

4-15 

, 5-7, 

11-45, II 

-72, 11-78 

to 11-79 

NUM, 4-8, 

4-13, 

4-15 

, 5-7, 

11-112 




POS, 4-4, 

4-8, 

4-13, 

4-15, 

5-3, 5-7, 

5-9, 

11-79 

, 11-134 

VAL, 4-9, 

4-13, 

4-15 

, 5-7, 

5-10, II- 
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variables. 

3-6 to 

3-7, 

4-16, 


11-53, 11-80 to 11-81, 
Glossary-5 

array, 3-6, 4-16, 11-45 
scalar, 3-6, 4-16, 11-53, 
II-lll, Glossary-4 


Object file, 1-6, 6-10 
Object program, 1-6 
running, 1-13 

ON statement, 4-13, 6-1, 11-113 
One-dimensional array, 3-14 to 3-16 
column vectors, 3-14, 9-4, 11-45 
compared to two-dimensional 
array, 3-14 to 3-16 
lists, 3-14 

singly-subscripted arrays, 3-14 
vectors, 3-14, 9-4, 11-45 
OPEN statement, 8-5, 8-8 to 8-10, 

8- 11, 8-12, 8-14, 11-107 to 
11-109, 11-115, 11-144 

Operators 

aphanumeric, 5-1 to 5-4, 11-121 
arithmetic, 4-1 to 4-3, 4-5 
assignment, 4-1 to 4-2 
assignment operator, 5-1 to 5-2 
Boolean, 1-2, 9-1 
concatenation operator, 5-2 to 
5-3 

definition of, 4-1 
logical, 5-12 to 5-13 
numeric, 4-1 to 4-16 
relational, 4-1, 4-4, 5-3 to 
5-4 

Operations 

Binary, 4-7, 4-14, 4-15 
Unary, 4-2, 4-3 
OPTION BASE statement, 11-120 
OR logical operator, 5-11, 5-12, 

9- 1, 11-121 

Other numerical functions, 11-97 
Output, 7-1 

DISPLAY statement, 1-2, 7-1, 7-3, 
7-17 to 7-18, 11-46 
PRINT statement, 4-5, 7-1 to 7-3, 

7- 6, 7-17, 11-69 to 11-70, 
11-135 to 11-139 

Output mode, definition of, 8-9, 

8- 11, Glossary-5 
Overflow, 4-14 
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P 


PACK statement, 11-122 to 11-123 
PAGE, 11-137 
Pagination, 2-7 
Parentheses, 4-3 to 4-4, 5-11, 

6-10, 6-16, 

PMAP, B-1 to B-2 
PI function, 4-6, 4-16, 11-107, 
11-122, 11-133 
PIC, 11-48, 11-112, 11-162 
Pointer, 11-142 
POS clause, 11-50 

POS function, 4-4, 4-8, 4-13, 4-15, 
5-3, 5-7, 5-9 to 5-11, 11-79, 
11-134 

Print elements, 11-135 to 11-139 
Print files, 8-3, 11-24, 11-143, 
Glossary-5 

PRINT statement, 4-5, 7-1 to 7-3, 

7-6, 7-17, 11-50, 11-65, 11-69 
to 11-70, 11-135 to 11-139 
PRINT USING statement, 7-8, 11-50, 
11-69 to 11-70, 11-135 
Printer output, 7-2 to 7-3 
expanded print, 7-3 
line feed, 7-3 
Prname, definition of, 8-7, 
Glossary-5 

Program development, 1-5 to 1-12 
Program Function keys (PF), 1-2, 

I- 3, 6-7, 7-14, 11-38, 11-74 to 

II- 75, 11-148 
Pseudorand, 11-152 
Pseudovariable, definition of, 

Glossary-5 

PUT statement, 8-12, 8-15, 8-20, 
11-56, 11-69, 11-140, 11-150 

R __ 


Radian measure, 406 
Random access, definition of, 
Glossary-5 

RANDOMIZE statement, 11-141, 11-152 
READ File statement, 8-10, 8-12, 

8-13 to 8-19, 8-20, 11-143 to 
11-144 


READ statement, 4-13, 5-17, 11-56, 
11-142, 11-165 

relationship to DATA statement, 
8-20, 11-142 
relationship to RESTORE 
statement, 11-142, 11-146 
Receiver, 3-2, 6-17, Glossary-5 
Record 

area, 8-11 to 8-12 
compression, 8-4 
length, 8-4 
types, 8-4 

RECORD function, 11-144 
Relational expression, definition 
of, Glossary-5 

Relational operators, 4-1, 4-4, 

5- 3 to 5-4 

REM statement, 2-6, 11-145 
Reserved words, 2-4, A-1 to A-2 
RESTORE statement, 4-13, 11-142, 
11-146 

RETURN CLEAR statement, 6-5, 

11-39, 11-57, 11-58, 11-74, 
11-149 

Return code, 1-11 to 1-12 
RETURN statement, 2-1, 6-1, 6-2, 

6- 5, 6-8, 8-19, 11-39, 11-40, 
11-57, 11-58, 11-74, 11-148 

used with GOSUB, 11-57, 11-148 
used with GOSUB', 11-39, 11-40, 
11-57, 11-74, 11-148 
REWRITE statement, 8-10, 8-11, 
8-15, 8-20, 11-56, 11-77, 
11-84, 11-150 to 11-151 
restriction on use, 11-136 
RND (random number) function, 

4-8, 4-9 to 4-11, 4-16, 11-152 
ROTATE[C] statement, 9-1, 11-153 
ROUND function, 4-8, 4-9, 4-11, 
4-16, 11-152, 11-154, C-3 

S_ _ 


scalar, definition of, Glossary-5 
scalar variable, 3-1, 3-6, 3-10 to 
3-14, 5-15, 11-53, Glossary-5 
SEARCH statement, 4-4, 11-155 to 
11-156 


Index-11 



INDEX (continued) 


SELECT file statement, 8-5 to 
8-7, 8-8, 8-11, 8-17, 11-159 
to 11-161 

SELECT PRINTER statement, 7-3 
SELECT statement, 4-6 to 4-7, 7-1 
to 7-3, 7-17, 8-17, 8-20, 

11-24, 11-30, 11-65, 11-77, 
11-157 to 11-158 

Sequential access, definition of, 
Glossary-5 

SGN (signum) function, 4-9, 4-11, 
4-13, 4-15, 4-16, 11-104, 

11-162 

Shared mode, definition of, 8-10, 

8- 11, Glossary-5 

SIN (sine) function, 4-1, 4-6, 

4-16, 11-103, 11-163 
SIZE function, 4-6, 4-9, 4-13, 

4-15, 8-18, 11-164 
SKIP clause, 11-50, 11-138 
SKIP statement, 8-10, 8-20, 11-165 
Sort (matrix), 9-3, 11-79 

ascending, 9-3, 11-86 to 11-87 
descending, 9-3, 11-86 to 11-87 
Sort statements, 9-3, 11-86 
Source file, 1-6, 6-10 
Source listing, B-1 
Source program, 1-6, 2-1 
SPACE keyword in OPEN statement, 
11-116 

Spaces, in statements, 2-3 to 2-4 
SQR (square root) function, 4-1, 
4-9, 4-16, 11-104, 11-166 
Statement, definition of, 2-1 
Statement labels, 1-1, 6-2 to 6-3, 
Glossary-5 

Statements, 2-1, 2-2, (see also I/O 
statements and individual 
entries) 

ACCEPT, 1-2, 4-13, 5-17, 6-2, 

7-2, 7-6, 7-9 to 7-18, II-3 
to II-8 

arithmetic (matrix), 9-2 to 9-3 
array dimensioning, 9-3 to 9-4 
assignment statement (matrix), 

9- 2 

CALL, 2-5, 4-13, 6-1, 6-2, 6-4, 
6-8 to 6-17, 11-20 to 11-22, 
11-31, 11-169 


Statements (continued) 

CLOSE, 8-5, 8-8, 11-23 
COM, 2-2, 3-10, 3-11, 3-14 to 
3-17, 6-10, 6-13, 6-14, 6-16, 
11-25 to 11-26, 11-43, 11-88, 
11-91, 11-97, 11-102, 11-170 
continuation of, 2-5 
CONVERT, 6-2, 9-1, 4-13, 11-27 to 
11-28 

COPY, 11-29 

DATA, 2-2, 11-33, 11-97 
data conversion, 9-1 
DEF, 2-2, 4-12, 11-35 to 11-36 
DEF FN', 2-2, 6-4 to 6-7, 6-18, 
11-38, 11-74 

DELETE, 8-10, 8-11, 8-12, 11-42 
DIM, 2-2, 3-10, 3-11, 3-14 to 
3-17, 11-43 to 11-44, 11-88, 
11-91, 11-97, 11-102, 11-170 
DISPLAY, 7-1, 7-2, 7-17, 11-46 
EJECT, 2-2, 2-4, 2-6, 2-7, 11-47 
END, 4-13, 6-1, 11-48 
FMT, 2-2, 7-6, 7-7 to 7-8, 

8-12 to 8-16, 11-50 to 11-52, 
11-150 

FOR, 2-5, 6-1, 6-2, 11-53, II-lll 

FORM, 2-2, 11-54 

GET, 4-13, 5-17, 8-12, 8-14, 

8-20, 11-56, 11-69, 11-144, 
11-165 

GOSUB, 2-5, 6-1, 6-2, 6-4 to 
6-8, 8-19, 11-57, 11-113, 

11-148 

GOSUB', 2-5, 4-13, 6-1, 6-2, 6-4 
to 6-8, 11-39, 11-40, 11-58, 
11-74, 11-148 

GOTO, 2-1, 2-5, 4-13, 6-1, 6-2, 
8-19, 11-60, 11-113 
HEXPACK, 9-1, 11-62 to 11-64 
HEXPRINT, 11-65 
HEXUNPACK, 9-1, 11-66 
IF, 2-1, 6-1, 6-2, 11-67 to 
11-68 

IF THEN, 4-4, 2-1, 6-1, 6-2, 

11-67 to 11-68 

IF ... THEN ... ELSE, 2-5, 6-1, 
6-2, 11-67 to 11-68 


Index-12 



INDEX (continued) 


Statements (continued) 

Image (%), 2-2, 2-4, 7-6 to 7-7, 
7-8 to 7-9, 8-12 to 8-16, 

11-50, 11-69 to 11-70, 11-136, 
11-150 
INIT, 11-71 

INPUT, 4-13, 6-2, 6-4, 7-2, 7-5, 

7- 9, 11-38, 11-39, 11-72 to 
11-75 

labels, 1-1, 6-2 to 6-4, 
Glossary-5 

LET, 2-1, 4-2, 4-5, 4-13, 5-17, 
11-80 to 11-81 

MAT ASORT/DSORT, 9-3, 11-86 to 
11-87 

MAT CON, 9-2, 11-88 
MAT IDN, 9-2, 11-90 
MAT INPUT, 9-2, 9-3, 11-85 to 
11-87, 11-90 to 11-92 
MAT INV, 9-3, 11-93 to 11-94 
MAT PRINT, 9-2, 11-89, 11-90, 
11-94, 11-95, 11-96 
MAT READ, 9-2, 9-3, 11-97 
MAT REDIM, 6-18, 9-3, 9-4, 11-43, 
11-98, 11-170 
MAT TRN, 9-2, II-lOl 
MAT ZER, 9-2, 11-102 
MAT =, 9-2, 11-89 
MAT +, 9-3, 11-85 
MAT -, 9-3, Il-lOO 
MAT *, 9-3, 11-95 
MAT 9-3, 11-99 

matrix statements, 9-1 to 9-4 
multiple lines, 2-4 
NEXT, 2-5, 6-1, 6-2, 11-53, 

II-lll 

ON, 4-13, 6-1, 11-113 
OPEN, 8-5, 8-7, 8-8 to 8-10, 

8- 11, 8-12, 8-14, 11-115 to 
11-119, 11-144 

OPTION BASE, 11-120 
$PACK, 11-124 to 11-132 
PACK, 11-122 to 11-123 
PRINT, 4-5, 7-1 to 7-3, 7-6, 

7-17, 11-50, 11-65, 11-69 to 
11-70, 11-135 to 11-139 
PRINT USING, 7-8, 11-50, 11-69 to 
11-70, 11-135 


Statements (continued) 

PUT, 8-12 to 8-16, 8-20, 11-56, 
11-69, 11-140, 11-150 
RANDOMIZE, 11-141, 11-152 
READ, 4-13, 5-17, 8-20, 11-56, 
11-142, 11-165 

READ File, 8-10, 8-11, 8-12, 

8-13 to 8-16, 11-56, 11-143 to 
11-144 

REM[ARK], 2-2, 2-4, 2-5, 11-145 
RESTORE, 4-13, 11-129, 11-142, 
11-146 

RETURN, 2-1, 2-5, 6-1, 6-2, 6-5, 

6- 8, 8-19, 11-39, 11-40, 11-57, 
11-58, 11-74, 11-148 

RETURN CLEAR, 6-5, 11-39, 11-57, 
11-58, 11-74, 11-149 
REWRITE, 8-10, 8-11, 8-12, 8-13 
to 8-16, 8-20, 11-56, 11-77, 
11-84, 11-150 to 11-151 
ROTATE[C], 9-1, 11-153 
SEARCH, 4-4, 11-155 to 11-156 
SELECT, 2-2, 4-6 to 4-7, 7-1 to 

7- 3, 7-17, 8-20, 11-30, 11-65, 
11-77, 11-157 to 11-158 

SELECT File, 8-5 to 8-7, 8-8, 

8- 11, 8-17, 11-159 to 11-161 
SELECT PRINTER, 7-3 

SKIP, 8-10, 8-12, 8-20, 11-165 
sort (matrix), 9-3, 11-86 to 
11-87 

STOP, 6-1, 6-2, 6-5, 6-7, 7-2, 

7- 17, 11-38, 11-39, 11-167 
SUB, 2-2, 4-13, 6-9 to 6-16, 

11-169 

TITLE, 2-2, 2-4, 2-6, 2-7, 11-174 
TRAN, 5-17, 9-1, 11-175 
$UNPACK, 11-124 to 11-132, 

11-177 

UNPACK, 11-176 

WRITE, 8-10, 8-11, 8-12, 8-13 to 

8- 16, 8-19, 11-56, 11-77, 

11-84, 11-179 to 11-180 

XOR, 5-11, 5-12, 9-1, 11-181 
STEP, 11-53, II-lll, 11-155 
STOP statement, 6-1, 6-4, 6-7, 

7-16, 11-38, 11-39, 11-167 


Index-13 



INDEX (continued) 


STR (portion of string) function, 

5-6 to 5-7, 5-14, 11-78 to 
11-79, 11-168 

String dimension, definition of, 
Glossary-5 

SUB statement, 4-13, 6-8 to 6-16, 
11-169 

SUBCHK, B-3 

Subroutines, 6-4 to 6-18 
CVDQ, 3-3, 11-31 
CVQD, 3-3, 11-32 
definition of, 6-4, Glossary-5 
external, 6-8 to 6-18 
GOSUB, 6-4 to 6-5, 11-57 
GOSUB', 6-5 to 6-7, 11-39, 11-40, 
11-58, 11-74 
internal, 6-4 to 6-5 
nested, 11-41 

Subscript, 6-18, 11-120, Glossary-6 

Substring, 11-155, Glossary-6 

SYMB, B-2 

Syntax, II-l 

T 


TAB clause, 11-50, 11-138 
TAB key, 7-13 

TAN (tangent) function, 4-6, 

4-16, 11-103, 11-172 
THEN keyword in IF statement, 

6-1, 6-2, 11-67 to 11-68 
TIME function, 5-6, 5-14, 11-173 
TITLE compiler directive, 2-7, 
11-174 

TO argument, 11-155 
TRAN statement, 5-16 to 5-17, 9-1, 
11-175 

Trigonometric functions, 4-6 to 
4-7, 11-103 

Two-dimensional arrays, 3-14 to 
3-16 

doubly-subscripted arrays, 3-15 
matrices, 3-15 
tables, 3-15 


User-defined functions, 4-11 to 
4-13, 4-15 

User File Block (UFB), 8-5, 8-6, 
8-8, 8-11, 11-160 
USING clause, 8-13, 8-14, 8-16 

V 


VAL function, 4-9, 4-13, 4-15, 

5-7, 5-10, 9-1, 11-178 
Variable, 3-1 
common, 6-10 
definition of, 3-1, 4-5, 
Glossary-6 

dummy, 4-12, 4-13, 6-6, 11-36 
loop, 11-53 

scalar, 3-6, 4-16, 11-53, II-lll 
use in LET statements, 11-80 to 
11-81 

Variable name, 1-1 

definition of, 3-1, 3-2 
Verbs, 2-2 

Volume, 1-5, Glossary-6 
VS Operating System, 1-4 to 1-5 

W 


Word, definition of, Glossary-6 
Workstation, 1-2 to 1-3, 7-1 to 

7- 18 

display, 7-3, 11-46 
programming considerations, 7-17 
to 7-18 

Workstation I/O, 7-3 to 7-16 
FAC (Field Attribute 
Characters), 7-4 to 7-5 
scrolling, 7-4 
wraparound, 7-4 
WP files, 8-3, Glossary-6 
WRITE statement, 8-12, 8-13 to 

8- 16, 8-20, 11-56, 11-77, 
11-84, 11-165 to 11-166, 

11-179 to 11-180 


U 


Unary operations, 4-2, 4-3 
UNPACK statement, 11-176 


Index-14 



INDEX (continued) 


X 


XOR logical operator statement, 
5-11, 5-12, 11-181 
XREF, B-2 

XX clause, 7-7, 11-50 

$ _ 


$PACK data format, 11-130 
$PACK statement, 11-124 to 11-132 
$UNPACK data format, 11-130 
$IINPACK statement, 11-124 to 
11-132, 11-177 


2200 


2200 disk storage format, 11-119 
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Customer Comment Form Publication Number_ 800-1202E 

THIe_VS BASIC LANGUAGE REFERENCE 


We've worked hard to make this document useful, readable, and technically accurate. Did we succeed? Only you can tell us! 
Your comments and suggestions will help us improve our technical communications. Please take a few minutes to let us 
know how you feel. 


How did you receive this publication? 

How did you use this Publication? 


□ 

Support or 

□ 

Don't know 

□ 

Introduction 

□ 

Aid to advanced 



Sales Rep 




to the subject 


knowledge 


□ 

Wang Supplies 
Division 

□ 

Other 

□ 

Classroom text 

(student) 

Classroom text 

(teacher) 

Self-study 

text 

□ 

Guide to operating 
instructions 

As a reference 
manual 

Other 


□ 

From another 



□ 

□ 



user 






□ 

Enclosed 



□ 

□ 



with equipment 














Please rate the quality of this publication in each of the following areas. 

Technical Accuracy — Does the system work the way the manual says it does? Q 
Readability — Is the manual easy to read and understand? 

Clarity — Are the instructions easy to follow? 

Examples — Were they helpful, realistic? Were there enough of them? 

Organization — Was it logical? Was it easy to find what you needed to know? 

Illustrations — Were they clear and useful? 

Physical Attractiveness — What did you think of the printing, binding, etc? 

Were there any terms or concepts that were not defined properly ? □ YD N If so, what were they ? 


EXCELLENT 

GOOD 

FAIR 

POOR 

VERY 

POOR 

? □ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 

□ 


After reading this document do you feel that you will be able to operate the equipment/software ?□ Yes □ No 

□ Yes, with practice 


What errors or faults did you find in the manual ? (Please include page numbers) 


Do you have any other comments or suggestions? 




Name 

Street 


Title 

City 


Dept/Mail Stop 

State/Country 


Comoanv 

Zio Code 

Teleohone 

Thank you for your help. 


All comments and suggestions become the property of Wang Laboratories, Inc. 
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To Order by Phone, Call: 

(800)225-0234 





Order Form for Wang Manuals and Documentation 


0 Customer Number (If Known) 


©Bill To: Ship To: 


© Customer Contact: 0Date Purchase Order Number 

i_)_(_1__ 

Phone_Name_ 


©Taxable ©Tax Exempt Number ©Credit This Order to 

Yes □ A Wang Salesperson- 

No □_Please Complete Salesperson's Name Employee No. RDBNo. 


® Document Number 

Description 

Quantity 

© Unit Price 

Total Price 






























- 


Sub Total 


Authorized Signature Date 

□ Check this box if you woulcJ like a free copy of 

The Literature Catalog (700-7647) 

Less Any 

Applicable 

Discount 


Sub Total 


LocalStateTax 


Total Amount 



Ordering Instructions 

1. If you have purchased supplies from Wang before, and 
know your Customer Number, please write it here 

2. Provide appropriate Billing Address and Shipping Address. 

3 Please provide a phone number and name, should it be 
necessary for WANG to contact you about your order 

4 Your purchase order number and date. 

5. Show whether order is taxable or not. 

6. If tax exempt, please provide your exemption number. 


7 If you wish credit for this order to be given to a WANG 
salesperson, please complete 
8. Show part numbers, description and quantity for each 
product ordered. 

9 Pricing extensions and totaling can be completed at your 
option: Wang will refigure these prices and add freight on 
your invoice. 

10. Signature of authorized buyer and dale. 


Wang Supplies Division Terms and Conditions 



1 . 

2 . 


TAXES — Prices are exclusive of all sales, use. and like 
taxes. 

DELIVERY — Delivery will be F.O.B. Wang’s plant. 
Customer will be billed for freight charges: and unless 
customer specifies otherwise, all shipments will go best 
way surface as determined by Wang. Wang shall not 
assume any liability in connection with the shipment nor 
shall the carrier be construed to be an agent of Wang. 

If the customer requests that Wang arrange for insurance 
the customer will be billed for the insurance charges. 


3. PAYMENT — Terms are net 30 days from date of invoice. 
Unless otherwise stated by customer, partial shipments will 
generate partial invoices. 

4. PRICES — The prices shown are subject to change without 
notice. Individual document prices may be found in the 
Corporate Publications Literature Catalog (700-5294) 

5. LIMITATION OF LIABILITY — In no event shall Wang be liable 
for loss of data or for special, incidental or consequential 
damages in connection with or arising out of the use of or 
information contained in any manuals or documentation 
furnished hereunder. 
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